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***MOTICE*** 

***LIMITED HARRANH*** 

MISOSYS shall have no liability or responsibility to the purchaser or 
any other person, company, or entity with respect to any liability, loss, or 
damage caused or alleged to have been caused by this product, Including but 
not limited to any interruption of service, loss of business and anticipatory 
profits, or consequential damages resulting from the operation or use of this 
program. ^ 

Should this program recording or recording media prove to be defective 
in manufacture, labeling, or packaging, MISOSYS will replace the program upon 
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purchase. Except for this replacement policy, the sale or subsequent use of 
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***ATTEHTION*** 
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Contact the publisher for details. 
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FORWARD 

LC is an exciting product for the TRS-80 series of microcomputers. The 
power of the C language is beginning to be realized by many individuals. LC 
puts the power of C into your hands. The unique implementation of the LC/EDAS 
language development system provides most of the standard C language 
capabilities as described by Kernighan and Ritchie in "The C Programming 
Language" as well as an extensive macro assembler. 

LC has been under development for two years - going through various 
transitions of implementation. The product you now own, has many unique 
features. It will provide you with extreme fascination of new techniques in 
coding. You not only have the opportunity of learning a relatively new 
compiled language, but you also have the opportunity to instill '"advanced 
programming techniques into your programs. You will get out of LC much more 
than what you give it. If you are new to the C language, take the time to 
learn it. You will be greatly rewarded. 

The tenure of the LC project has been intriguing. That one word 

certainly does not sum up the entire history, however. No one word can. 

Frustrating, rewarding, despair, hope, and many other words can be added to 

the list. During LC's long labor, Jim's wife Sam, had some of her own, giving 
birth to a new daughter, Danielle. The encouragement and support that Jim's 

family provided him shall not go unnoticed - let alone the deep understanding 
of all those late hours at the computer. 

A special thanks goes out to Rich Deglin for his continued support 
throughout LC's design and implementation life cycle. Rich is also remembered 
for his contributions to the installation library of the string and control 
functions and his many suggestions of enhancements to the standard library. 
I'd like to "point" out that Karl Hessinger's plotting functions will be used 
by many LC programmers and will be most appreciated. 

To Jim Frimmel goes unending appreciation for a job well done. This 
astute mind has formed many of the sophisticated techniques inherent in LC. 
It has been my personal pleasure to have worked so closely with Jim over the 
long LC development time frame. It will be equally pleasurable to continue 
this association. Jim's efforts were sparked by the work done on the SMALL C 
compiler by Ron Cain - one who has certainly provided the foundation for a 
lot of C work. 

Lastly, let me acknowledge the understanding that my wife, Brenda, has 
demonstrated. Those long hours spent in putting this reference manual 
together were time apart from her. For a newly married couple, it was a noble 
sacrifice. It will not be forgotten. 
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FROM THE AUTHOR 

The product which you have in your hands, affectionately called "Elsie", 
has been a labor of love. She has grown with my children, who have shared in 
this labor by giving up time with their father. My wife, Sam, has nourished 
Elsie with her understanding, kindness and love, and has sacrificed her time 
as well. I have long awaited the day when Elsie would be completed, so that I 
could share more with them. This family, whom I love dearly, is my greatest 
earthly treasure, beyond price. My Heavenly Father's love and patience, and 
the gifts he has blessed me with, are what made it all possible. I pray that 
you will share in my blessings in some way, through whatever Elsie brings 
your way. 

Elsie has grown from a "small seed" of generosity: Ron Cain's^^Small-C 
compiler. Ron published his compiler and placed it in the public domain for 
all to hack, and many have done so. Ron Cain deserves our heartfelt thanks 
for stirring up interest in the C language and for getting us started. Elsie 
was "bootstrapped" using Small-C, and she shows her roots in places. It is my 
hope that Elsie will bring the C language to a less experienced audience than 
that which the language now appeals to. I am sure there are many who, with 
just a little help getting started with C, will become excellent C'ers. 

Elsie would not be here if it had not been for Roy Soltoff of MISOSYS. 
He has been a generous benefactor and friend, giving of his time, hardware 
and software to bring Elsie to you. His artist's eye also gave this manual 
the friendly feel and utility that his products are known for. What makes the 
N Elsie package especially unique is the work that Roy put into the EDAS IV 

assembler. This assembler is the best example of "user-driven" software that 
I know of. Roy listens to his users (and responds), and he has gotten quite 
an earful from me. Most of all, he has been more patient than I could have 
imagined, waiting for my perfectionist dreams to become useful reality. Roy's 
bride, Brenda, has displayed this same patience and kindness, with nary a 
protest. I'm sure many others are with me when I say, thank you and may God 
bless you both. 

Elsie has been helped along the way to becoming a product by some good 
friends. Karl Hessinger and Rich Deglin were especially generous with their 
time and programming skills. Steve Hill and Scott Loomer also helped with 
suggestions, advice and feedback. Also, my wife Sam's editorial skills have 
resulted in an unusual combination: sound grammar in a technical manual. To 
all of you who have helped Elsie along, thank you and may God bless you. 

To my new daughter, Danielle Michelle, who, like Elsie, is full of 
bright promise and laughter. 



September 20, 1982 
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PREFACE 

Although considerable effort was expended to make the LC reference 
manual as complete as possible, this documentation package in no way is to be 
considered an instructive guide into the writing of C language source 
programs. Chapter two is a good definition of the C language as implemented 
in LC. Although some may find that complete enough, one reference text is 
available that must be added to your library. "The C Programming Language", 
by Brian W. Kernighan and Dennis M. Ritchie is the "bible" of C and is MUST 
reading. It is filled with numerous examples and illustrations of each C 
statement and also contains example upon example of useful functions. If you 
are new to assembly language, the preface contained in the EDAS reference 
manual should be consulted for additional information. 

The advice is to peruse the contents of both this LC reference manual 
and the EDAS reference manual to familiarize yourself with its information 
and content. If you have any questions concerning the LC development system, 
feel free to call or write; however, since the results of a C program rely 
heavily on exact syntax, if your question concerns any aspect of the C 
language, it must be submitted in writing. All transactions need to be 
identified with your registration number(s) so be prepared to provide both 
your LC and EDAS registration numbers. It would also be helpful to make sure 
your questions are not answered in the manual. 

Speaking of registrations, MISOSYS would like to provide you with the 

_ best technical support possible. To provide this support, we need to know who 

^ our customers are. So please fill out the registration form packaged with the 

^ diskette and return it to us promptly - postal card postage is sufficient. 

The registration number located on the diskette labels must be entered onto 

the registration card and should also be entered in the space provided below. 

The registration number must be mentioned on all correspondance with us or 

when telephoning for service, so don't lose it. 



Registrations: LC EDAS 
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Before diving into Elsie, we suggest that you do the following, at a 
minimum: 

1> Read the entire introduction to get an idea of what LC is all about. 

2> Make backup copies of the distribution diskettes. Elsie is released 
on two distribution diskettes. The diskette labeled "LC, contains the LC 
compiler and all support libraries. The second diskette labeled "EDAS", 
contains the macro assembler and editor and various EDAS support utilities. 
Me suggest that you make one set of archival backups and store them away in a 
secure area (safe from dust, dirt, magnetic fields, etc.). Then make a 
working backup of the distribution diskettes. The procedures for.^ making 
backup copies can be located in the UTILITY section of your LDOS user' manual 
under "BACKUP". For your information, LC is distributed on data diskettes. 

3> Create an LDOS system diskette with a maximum of free space. If you 
are going to BOOT from this diskette, then you will need a configuration that 
includes the LDOS keyboard driver at the barest minimum. Also, if you are 
using a Model I, use the CDO/FLT filter in your configuration to filter the 
video driver. The filter presents more usable character indications for the 
characters, M [\ "\\ "]", "~", and """. This "working system diskette" can 
be created by using the LDOS PURGE utility on a fresh backup of LDOS. You may 
remove all files except SYS0-SYS4, SYS6, SYS8, SYS10-SYS12. Keep any other 
file you use frequently (for Instance, BACKUP and FORMAT), if you are using a 
~~\ double density system, follow steps <3A>. If you are using a single density 
' system, follow steps <3B>. 

3A>-A 40-track double density minimal system diskette per 
the above has about 144K free. Copy EDAS/CMD from the 
working EDAS diskette. Then copy all of the files from the 
working LC backup to this LC system diskette. This should 
still leave some work space. Use a data diskette in your 
second drive for LC source files and all files output by LC 
and EDAS. 

3B> A 35-track single density minimal system diskette per 
the above has about 57K free. Copy EDAS/CMD from the 
working EDAS diskette, then copy LC/CMD, LC/JCL, LC/ASM, 
LCMACS/ASM, and STDIO/CSH from the working LC backup to the 
new system diskette. We'll call this diskette your LC 
System diskette. Now remove the LC/CMD, LC/JCL, LC/ASM, 
LCMACS/ASM, and STDIO/CSH files from the working LC backup 
(the one you just copied FROM - not the system disk that 
just received those files). Re-designate this disk your 
working LC Data disk. In a two drive system, your work 
files (LC source and output files) will need to be stored 
on this LC Data disk. Therefore, make a few backups of this 
disk to use for various LC programming sessions. 

4> Notice that LC requires a two drive system. If you have a one-drive 
system, you overlooked the machine requirements noted in the LC 
advertisements and in the catalog. We would not want any user so frustrated 
~~"' with trying to utilize the LC compiler system on a single-drive computer. 

• 
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5> If you are really anxious to proceed and create a working C-language 
program, turn to the OPERATOR'S GUIDE page 3-10 and note the "simple > 

exercise". Place the LC system diskette in drive 0, the LC data diskette in 
drive 1, and proceed with the EXERCISE. 

6> Read the rest of the LC user's manual. Pay particular attention to 
the OPERATOR'S GUIDE and the LANGUAGE DEFINITION chapters. Skimming is OK for 
technical details, but get a feel for where things can be found in your LC 
manual . 

7> Have fun with Elsie! 
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ELSIE FILES 

szsssasssss 



Elsie comes complete with everything you will need to turn your LC 
source programs into executable CMD programs. There are many files on your 
distribution diskettes: a compiler, an editor/ assembler, utilities, 
libraries, and JCL files. Here is a description of some of these^ files and 
their uses: 

LC/CMD 



This is the LC language compiler. LC accepts as input, C source code 
files, and outputs an EDAS Version IV compatible assembly source file. In 
order to organize files in a structured manner, LC source code files have a 
file extension of VCCC" and LC output assembler files have a file extension 
of "/ASM". 

LC/LIB 



This is the standard function library. It is an implementation of the 
portable library available under most installations of C compilers. These 
x functions allow programs to be written which will be directly usable under 
other C language systems that have the standard library available. The 
standard functions perform such tasks as input/output, dynamic memory 
allocation, -standard I/O redirection, and string handling. The standard 
library was designed to be compatible with the standard library under Western 
Electric' s UNIX operating system. 

FP/LIB 



This contains the LC floating point function library. LC does not have 
floating point variables built into the language itself. However, this 
library supplies access to the floating point routines in the TRS-80 ROM 
through functions. Single and double precision arithmetic, as well as 
trigonometric and transcendental functions, are included. FP/LI8 also 
includes functions for converting between ASCII, integer, single and double 
precision variables. 

IN/LIB 



The installation function library is contained in this module. These 
functions supply graphics plotting, string manipulation, certain LOOS entry 
points, and other TRS-80 features. 
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STDIO/CSH 



The standard I/O header file supplies constants 
are needed to use the standard I/O library (LC/LIB). 



and definitions which 



LC/ASM 



This file is 
accesses your "main 
between your program 
CMD program. 



the primary assembler 

M 



source file assembled by EDAS. It 
program and establishes the neccessary interfacing 
and the LC runtime modules needed to make a "complete" 



LCMACS/ASM 



This file contains the #option defaults and assembly language macros 
referred to by the compiler and used by the assembler. This file is always 
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CDO/FLT 



This file is a video filter for the Hodel I machine. It provides a more 
reasonable and less confusing display of the characters: [» \, 3, *, "*. 
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LC was designed to be compatible with C programs written and intended to 
run under UNIX. Thus some features of UNIX were incorporated into the design. 
These features include standard I/O devices, standard I/O redirection, device 
independence, command line arguments, and dynamic memory allocation. 

To make C a portable language, the interface within a program to the 
external world 1s Isolated 1n a standard library. A program written in C 
using only the standard functions to perform input, output and memory 
allocation can be transported in source code form to another sytem, 

recompiled,, and run with minimal changes. The LC system includes a _ standard 
library which is compatible with programs developed under mti. Thus, 
programs developed under LOOS with LC will run under UHIX- as well. The 
reverse is also true, except 1n cases where features not implemented in LC 
are used in the program developed under UNIX. 

LDOS runs on a variety of machines, with many varied configurations of 
I/O devices. Any program written for one particular environment running LDOS 
can run on any other, provided that the standard library is utilized. The 
programmer should bear this in mind when writing programs to avoid 
conversions when migration to a new system becomes necessary. 
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STANDARD INPUT/OUTPUT 
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Any program generated by LC will normally have three files 'automatically 
opened when the program begins execution. These files are standard input, 
"stdin" (normally the console keyboard); standard output, "stdout" (normally 
the console display); and standard error, "stderr* (normally the console 
display). The program can access these files without opening them by using 
standard library functions since the LC standard library automatically opens 
these standard files. They are also automatically closed when the program is 
exited as well. Thus, the program which uses the standard I/O files 
exclusively can deal with input and output and leave the opening and closing 
to the LC standard library. 

1 
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STANDARD I/O REDIRECTION 
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The standard I/O files normally operate to and from the user's console. 
However, a facility is inherent within the LC standard library to permit you 
to "re-direct" any of the standard I/O devices - thus the term "I/O 
redirection". The user can give a file specification that will be used in 
place of the normal specification when a standard file is opened. This is 
done on the LDOS command line when the user executes the program. 

When the left angle bracket symbol, "<", appears on the command line, 
followed by a file specification, that file specification is used when the 
standard input file is opened. Similarly, the right angle bracket symbol, 
">", causes substitution of the standard output file specification, the "»" 
causes standard output to be appended to the redirected file/device, and the 
number sign symbol, "#", causes substitution of the standard error file 
specification. Spaces are NOT permitted between the redirection character and 
the file specification. 

It may not be immediately obvious how this feature can be used. Here is 
an example LC program that illustrates the straightforward use of standard 
I/O redirection. The following program can be used to copy any file to any 
other file (remember that "file" can be any device or LDOS disk file). 

/* CLONE - copy standard input to standard output */ 

#include stdio/ccc 

int c; 

main () 

{ "'while ((c » getcharO) !* EOF) putchar(c); } 

The example program simply copies the standard input to the standard 
output until end of file is reached. Once this program is compiled and 
assembled it can be used to copy any file to any other. For example: 

CLONE <CL0NE/CCC 

will display the file clone/ccc on the system console. The command: 

CLONE >*PR 

lets the user type to the system printer. If disk file copying. is needed, the 
command : 

CLONE <INFILE/ASM:1 >OUTFILE/BAK:2 

will copy the file "INFILE/ASM:1" to the file "0UTFILE/BAK:2". If the user 
wishes to have a printed log of any error messages that a program puts out, 
use something like : 

LC TESTLIB #*PR 

Any messages that LC outputs to the standard error file will be re-directed 
to the printer device in lieu of the console display. 
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STANDARD HEADER FILES 



Standard header files are files which contain definitions peculiar to a 
system. They usually take the form of "#define" statements and "extern" 

statements within the header file. In order to use certain - libraries, a 
corresponding header file should he included (using the "#include u 
statement). The file extension of "CSH" is used for "LC Standard Header" 
files. 



A program to be compiled and linked with LC 
"STOIO/CSH" included to compile properly. STDIO/CSH 
system dependent parameters, such as end of file (eof) 
<stdout>, <stdin>, and <stderr> are addresses 1n the 
do not need to be defined before use. 



should have the file 
also defines various 
and end of line (eol). 
standard library whiets 



The following listing 1s representative of 
with the LC package. 

/* ELSIE STANDARD I/O CONSTANTS */ 



the STDIO/CSH file Included 



#def1ne EOF 


-1 


#define eof 


-1 


#def1ne eol 


13 


Idefine EOL 


13 


#define FILE 


char 


Idefine NULL 





#def1ne TRUE 


1 


#def1ne FALSE 





#def1ne true 


1 


#define false 





Idefine OFF 





Idefine ON 


-1 
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FUNCTION LIBRARIES 
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Commonly used LC functions are collected into FUNCTION LIBRARIES. The 
functions in a library can be used by the programmer without the need to 
rewrite or recompile the functions needed. Once an LC program has been 
compiled, it can then be linked during the assembly phase with the functions 
it requires. Only those functions necessary for the execution of the program 
are linked to the compiled program. 

Certain functions required by many programs are included in a special 
library called the STANDARD LIBRARY. The standard library is the common 
denominator between all C language installations. Programs written using 
functions in the standard library are easily transported to any 7 other 
computer supporting a C language system with the standard library 
implemented. The most important aspect of the standard library is that it 
allows the details of each system's peculiar operating environment to be 
hidden from the programmer's view. The standard library provides the 
functions for input/output, memory allocation, and character set 
manipulations. In addition, a collection of subroutines used by the compiled 
C program to perform basic operations is also supplied in the standard 
library. 

Users can also create their own collections of often-used functions that 
can be used in the same manner as the standard library. These USER LIBRARIES 
reduce the. programming time, compilation time, and program complexity 
necessary in creating new programs. Functions, once defined, written, and 
tested, can be added to the user library and need only be referred to by name 
in later programs. The linking process brings the functions into subsequent 
programs without the need to recompile. If you want to create and maintain 
your own libraries, you will need the Partitioned Data Set (PDS) utility. 

Special purpose libraries may also be created for use in particular 
types of applications. For instance, the functions specific to the TRS-80 
are provided with your LC package are in the special purpose library, IN/LIB. 
This is an example of how the C language avoids the trap of non-standard 
extensions being included within the language. 
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LC encourages the use of structured programming methods. Unless one 
uses the "goto" statement heavily, LC practically demands a structured 
approach to program construction. This is not to say that writing programs 
with LC will automatically make you a good, structured programmer. This 1s a 
skill that is developed by learning and applying the basics. 

Some understanding of structured design concepts 1s necessary in order 
to effectively use LC. Probably the first frustrating thing that novice LC 
programmers will encounter, especially 1f their experience Is limited to 
BASIC and assembly language, is the discouragement of the use of "goto". 
Kernighan and Ritchie, in THF r. PROGRAMMING LANGUAGE, state that the "go*p" 
1s never necessary, and in practice 1t is almost always easy to write code 
without 1t. The concept to understand is that the "goto's" are hidden within 
the program statements. LC provides, in a coherent, understandable form, the 
program constructs that you have been building out of "goto's". 

Last but not least, several texts are available that should be part of 
your library. The first, THF c PROGRAMMING LANGUAGE by Brian W. Kernighan and 
Dennis M. Ritchie (published by Prent1ce-Hall), 1s the Bible of the C 
language and is a required part of your own library. We will refer to this 
book throughout this manual by the abbreviation, "K&R", for Kernighan and 
Ritchie. Two other books, ELEMENTS OF PROGRAMMING STYLE and SOFTWARE TOOLS , 
by Brian U. Kernighan and P. J. PI auger (published by Addi son-Wesley), -^ 
present a good foundation of structured programming concepts. Prentice-Hall / 
also publishes THE C PUZZLE BOOK by Alan R. Feuer. This book can be used to > 
test your understanding of the C language. It has proven itself to be quite 
useful 1n testing out the intricacies of the LC compiler. 
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The C language is, in a word, functional. The basic unit of program 
construction when using LC is the function. Every LC program is a collection 
of functions. Each function is a collection of statements that work together 
to achieve (hopefully) a useful, well-defined, purpose. 

Each function can have information passed to it when it is invoked 
("called"). The elements of information passed to the called function are 
denoted as arguments. In LC, arguments are copied onto the stack. The 
function can then access and use the "local" (known only to the called 
function) arguments, leaving the original copy of the arguments unchanged. 
Each argument is defined at the start of the function. Functions also 7 return 
values to the functions that call them. In LC this value is always a l6-1t 
number. The" value returned can be compared to, placed in a variable, etc. 
Functions can appear , in an arithmetic expression anywhere that a constant 
can. 

Here is an example of a function: 

square(num) 
int num; 
{ return num * num ; } 

The function, squareO, returns the square of a number; in other words, 
the argument, "num", is multiplied by itself and the result 1s returned. 
Arguments are listed in parentheses after the name of the function, separated 
by commas. These arguments must be passed by the calling function in the same 
order as they appear in this list. 

The BODY of the function is the group of executable statements that are 
within the braces "{» and ">". Actually, the grouping of statements in 
between braces denotes a special kind of statement called the COMPOUND 
statement. The compound statement is fully explained in the section on LC 
language statements. 

Every LC program has a special function called "main" which is always 
the entry point to the program. When referencing a function within this 
narrative, we will put "()" after the name to identify it as a function. This 
is close to the way it looks in an LC program. The function, mainO, calls 
other functions, which in turn call other functions, etc... Thus, each 
program is an hierarchical structure of functions, with mainO at the top of 
the hierarchy. 

The LDOS command line which invokes the LC program is passed to the 
function mainO using two parameters, "argc" and "argv". One LC program can 
invoke another program by using the cmd() function. When the called program 
finishes, a special function, exit(), is used to return a value to the 
calling program. Programs can call other programs, passing any arguments 
using "argc" and "argv". In a way, each program appears as a function to 
other LC programs and to LDOS. 
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Please scrutinize the illustration of functions in the following 
example: 

main() 

{ /* The "main" function ... 
execution begins here! 
*/ 
sayJielloO; 
do_work(); 
say goodbyeO; 

exif(0); /* a normal exit, no error code */ 
} /* sorry, we can't "goto" any of the functions below. */ 

sayJielloO *? 

{ ""puts( "Myall!"); putchar(eol); } 

say_goodbye( ) 

{ puts( "Bye y'all !!!"); putchar(eol); } 

do__work ( ) * 

< ~~ while (not quitting time) 
{ attachTnut,boltT; 
pass on(widget); 

> 
} 
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STATEMENTS - SIMPLE & COMPOUND 



To create an LC function .you have to state the action to be taken, using 
LC language STATEMENTS in the desired combination. Certain special statements 
are built into the language to provide the necessary programming constructs 
(sequence, iteration, selection). You may be surprised, at first, by the 
limited number of statements built into the C language. The authors of the 
language wished to maintain the generality of the programming statements, 
forcing any special features to be outside of the programming language 
itself. Other languages often have extensions in the form of statements to 
provide specialized features, leading to incompatible versions of the same 
language. BASIC is a well-known example of a language extended in far too 
many different ways. The C language avoids this situation by only providing 
those statements necessary for structuring the program's logical flow and by 
placing all special features into function LIBRARIES. Function libraries are 
nothing more than collections of commonly used functions. See the section on 
the LC libraries in the INTRODUCTION for more information. 

Simple LC statements always end with a semicolon ";", the STATEMENT 
TERMINATOR. The LC compiler depends on the semicolon to tell when a simple 
statement ends. Any number of simple statements may be entered, one after the 
other, to form a SEQUENCE of statements that are executed pne at a time, 
first to last. 

The brace characters, "{" and "}", are used to enclose a sequence of 
statements to form a COMPOUND statement. A compound statement can be used 
anywhere a simple statement can be used. Thus, the body of a function (that 
portion enclosed in braces) is just a special form of compound statement. 

For example: 

nl * 0; 

is a simple statement. However, the statement: 

< 

h » h / 2; x0 » x0 + h / 2; y0 » y0 + h / 2; 

x * x0 + 1 * 32; y ■ y0 + 10; u ■ x; v ■ y; 

++1; P( 1, 1 ); 

} 

is a compound statement. 
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DATA REPRESENTATION - CONSTANTS 
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Numbers and characters must be entered in your LC program in certain 
ways in order for the compiler to understand them properly. A fixed value to 
be used in an LC expression is called a CONSTANT. 

Where just a decimal number is required, you can enter it just as you 
write It. A leading zero indicates that the constant is in another base. A 
leading zero followed by a string of digits indicates an OCTAL CONSTANT. A 
leading zero followed by 'X« or 'x' indicates that a hexadecimal constant 
follows. Thus, the decimal number, 255, can be represented as 0377 or. 0xFF, 
as desired. _ 

If the variable to be assigned the constant is not big enough to contain 
the constant, only the least significant bits (LSB) of the number are stored. 
This is, in effect, storing the remainder of dividing the constant by 256 or 
65,536, depending on the variable size. No warning is given when this 
happens, so the programmer must be sure that the variable can hold the 
number. 

CHARACTER CONSTANTS supply a way to specify the code for a character 
which does not depend on any particular character set. A character constant 
is a list of characters within single quotes (apostrophes). For instance, the 
character constant 'A' Is stored in the computer as the -number 65 (in 
decimal). Again, it is up to the programmer to assure that the number of _ 
characters between apostrophes can fit into the variable being assigned. If j 
more characters are specified than can fit, only the last one or two (as J^ 
needed) are used. 

When a sequence of characters 1s needed, a STRING can be specified by 
enclosing the characters between quotes (sometimes called "double" quotes - 
i.e. "This is a string"). LC does not place all of these characters into a 
variable but rather the ADDRESS of the first character of the string. Thus, 
when the string, "testing, 1 2 3", is used in an LC program, the characters, 
between quotes are stored in memory, and the address of the first 'V 1s used 
in the expression where the string was specified. You can say that the number 
generated by LC to represent the string really POINTS to the string. The 
subject of POINTER variables, which are handy for manipulating strings, will 
be discussed later. 

There are certain control characters that are needed frequently in 
programs, but which differ from machine to machine. These can be represented 
in C programs using ESCAPE SEQUENCES, to provide a machine-independent 
constant. The backslash character, "\\ is called the ESCAPE CHARACTER and 
denotes the beginning of an escape sequence. A letter following the escape 
character indicates which control code is being specified. Also, certain 
characters that would otherwise be difficult to represent in strings and 
character constants are generated by following the backslash with the 
character. These escape sequences are shown in the following table: 
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1 Escape 








I Sequence 


Control Code 


ASCII 


code used by LC j 


33SS9BE<ESSSSEBS 


SS3SSSSSS5IS 


3S3XS3SS3SS333S33333SS 1 


1 \n,\N 


NEWLINE character 


xW 


CR | 


1 \t,U 


horizontal tab 


x'09' 


HT | 


1 \b,\B 


backspace 


x'08' 


BS | 


1 \r,\R 


carriage return 


x'0D' 


CR | 


1 UAF 


form feed 


x'0C 


FF | 


1 \\ 


backslash 


x«5C 


backslash | 


1 V 


single quote 


x'2C 


apostrophe I 


1 \9 


null 


xW 


null byte . I 


1 \" 


double quote 


X'22' 


double quote I 



••*? 



In addition, any binary code can be represented in a string or character 
constant by following the backslash with a numeric constant. This is done by 
following the backslash with up to three octal digits. An extension which is 
not normally allowed in the C language is offered in the LC language as a 
convenience to microcomputer users who are only familiar with hexadecimal. 
The backslash may be followed by an 'x 1 and one or two hexadecimal digits. 
Either of these two methods result in an 8-bit character constant. 



: \ 



For example, the character *A' can be represented as '\x41' using a 

hexadecimal escape sequence, or as '\101' 1n an octal constant. Similarly, to 

place a carriage return at the end of a line, the following three methods 
could be used: 



"An example of a normal escape: \n" 

"An example of a hexadecimal escape: \x0D" 

"An example of an octal escape: \015" 

When a character escape sequence is used within a string, the actual 
value of the escape sequence is stored in a string (i.e., only one byte of 
data per escape). Thus, the string: 

■\n\x0d\015" 

is only three bytes long in memory once the program is compiled and 
assembled. 
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The names given to Identify variables, functions, macros, and labels are 
called "identifiers" and all follow the same rules as to their format. LC 
identifiers may be of any length (be practical) and must start with an 
alphabetic character {'A' through 'Z', 'a* through 'z'} with the rest of the 
characters- in the name consisting of upper-case or lower-case alphabetic 
characters {'A' through 'Z', 'a* through 'z'}» numeric characters {0 through 
9}, or the underline character {_}. LC will accept an underline as the first 
character of an Identifier, however EDAS will not; therefore, do not start an 
identifier with the underline character. 

LC remembers only the first eight (8) characters of an identifier, so 
these first eight must be unique. -*, 

Elsie is case-sensitive, i.e., recognizes the difference between 
lower-case and upper-case in identifiers. Thus, "EOF", "eof", and "Eof" are 
all different identifiers to Elsie. However, identifiers which must be 
written out in assembler source code for EDAS are converted to upper-case, 
since EDAS does not allow lower case assembly language code. A good, simple 
rule to follow is to use IPPER-ease fo^macro constants only., and lower-case 
for all other identifiers. Since macro identifiers are not written to the 
assembly output file, they will not conflict with any other identifiers which 
are the same, except for case differences. 
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DATA DECLARATIONS 



LC variables must always be declared before use. The standard procedure 
is to declare variables at the beginning of the program (globals) and at the 
beginning of each function (locals). 

Character variables are stored in eight bits, or a byte. The 
declaration: 

char c, string[81]; 

establishes a character variable named "c" and a character array named 
"string". Arrays of one dimension are allowed. *** 

All other variable types (short, long, int, unsigned), as well as 
pointers, are stored in sixteen bits. The short and long declarations are 
provided in the interests of portability. The declarations: 

int a; 

short b; short int b2; 

long c; long int c2; 

are all acceptable declarations, and all result in the same size integer 
field. This is acceptable, since the C language does not guarantee that a 
-^ "long" will, be longer, or that a "short" will be shorter than integers. 

Integers declared In this manner are signed, I.e., their most significant bit 
is regarded as a sign bit. Their values can range from -32,768 to 32,767 
(decimal). Unsigned fields do not have a sign bit. They range from to 
65,535 (decimal) and are declared like this: 

unsigned u; 
unsigned int u2; 

Arrays of one dimension are allowed for short, long, int, and unsigned 
types. 

Pointer variables are different from the types described so far, in that 
they normally contain the ADDRESS of a data item. For example, 

char *cp; 

declares a pointer variable named "cp". The asterisk denotes INDIRECTION, 
I.e., that the data item is referred to indirectly through the pointer 
variable "cp". The address of the data item must be stored in the variable, 
"cp", before it is used as a pointer to access a data item. To refer to the 
data itself, an asterisk is placed before the name, e.g., *cp denotes the 
data item. An example of practical use follows: 
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getlt(cp) 

char *cp; 
{ while ((c»getchar()) !» eol && c ! a EOF) 
{ *cp ■ c; 

++cp; 
> 
. *cp*NULL; 
return c; 
> 



The function, getitO, inputs characters continually from the standard 
input until end-of-file or end-of-line characters are encountered. When 
getitO is called, the pointer argument, cp, contains the address of a buffer 
area. One by one the characters are placed in the buffer, (*cp ■ c), and the 
buffer pointer is incremented (++cp). ^ 

Pointers may be declared for any data type. An alternative way of 
declaring a pointer is to leave out the size in an array declaration. For 
example, 

int countfj; 

declares an integer pointer, "prime". There is good reason for this method of 
declaring a pointer. Pointers may be INDEXED to get to the "nth" item in an 
array. Using the example above, count would contain the address of the 
beginning of an array of short integers. "count[03* denotes the first 
element in the array, and "count[223" denotes the 23rd element. 

No matter how a pointer is declared, either method of using the pointer 

may be used as the programmer sees fit. Thus, "•♦count" and "count[03" refer 

to the same data item and may be used interchangeably in the same program. 
Using "♦count* is a little more efficient, however. 

Pointers may point to other pointers. This bombshell of a statement is 
probably too much for you after the last few paragraphs; it must be said, 
however. LC allows pointers to have more than one LEVEL OF INDIRECTION. This 
can be declared several ways; 

shlneO 

{ char *namesG; 
char *(*words); 

Both of these declarations result in the same effect: a pointer which points 
to a pointer which points to a character field. 

Pointer variables may have up to 32 levels of Indirection. However, the 
practical limit is the ability of the programmer to keep track of all this. 
In general, two levels of Indirection are all most folks can take. 

More information and examples can be found in the reference text, "The C 
Programming Language", by Kernighan & Ritchie. 
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Variables or functions which are declared outside of any function, i.e, 
are not parameters to functions or declared with braces, are called 
"external ". They are external to all functions. External variables and 
functions can be used from any of the functions within the module being 
compiled. Using the "extern" statement, an external variable or function may 
even be accessed from another, separately compiled, module. Please do not 
confuse "extern" and external. External (to all functions) variables and 
functions can be declared without the "extern" statement. The "extern" 
statement is explained in full detail below. 

Variables declared within a function are called "local". Functions may 
not be defined within another function, as is the case with the Pascal 
language. However, a function may be DECLARED "extern" so that it may be 
accessed within the currently defined function. Local variables may not be 
accessed from any other functions. They only exist for the function in which 
they are declared. Even within the function, a local variable can only be 
accessed in the block in which it is declared. Remember, a block is a section 
of code contained within a matching pair of braces. 

Local variables can have the same name as external variables, or local 
variables declared in different blocks. If a local variable has the same name 
as an external variable then the local variable is the one accessed when used 
within the local block. In the following example: 

int same; 
-funk (same) 
{ return same; } /* return local copy */ 
hunkO 

{ if (blockj) 
{ int same; 

/* some code could go here */ 
> 

else 
{ char same; 

/* some other code here */ 
} 
> 

e^ery declaration of "same" was a unique variable. Although legal, the 
declaration of local variables with the same name within the same function is 
not recommended. This type of trickery, as shown in hunkO, needlessly causes 
confusion and is easily avoided. 
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Variables and functions may be declared as being in certain classes. 
These classes specify where variables are to be stored. The classes available 
in LC are: auto, static, extern, and register. The storage class of an object 
is specified by placing the class name in front of the normal declaration: 

auto char c; 
static 1nt ali^f}; 

STORAGE CLASS - AUTO 

Variables which are declared "auto" are stored on the stack. This is the 
default for variables declared within a function, so the declaration may 
therefore be omitted. Local variables which are "auto" are created afresh 
each time the function in which they are declared is called. This allows 
functions to be reentrant and recursive. Functions may not be declared with 
class "auto" since a function must be declared outside of any other function. 
As K&R say, the C compiler is incapable of compiling code onto the stack! 

The scope of an auto variable is the block (within braces) in which it 
is declared. All other portions of the code being compiled are oblivious to 
the existence of the auto variable, and in fact there may ..exist other 
variables with the same name. 

.; — * : ^ 

The auto class is illegal for functions and other external definitions y 
(any variables declared outside of a function). — ' 

STORASE CLASS - REGISTER 

Variables declared in the register class are regarded as auto variables 
h^ LC, since the Z-80 has no extra registers available for use as register 
variables. Register variables are stored on the stack 1n the same manner and 
are also illegal outside of a function. 

The scope of register variables is the same as that for auto variables. 

STORAGE CLASS - EXTERN 

The "extern" storage class allows an external variable declared in one 
module to be accessed from another module. A "module" 1s what is processed by 
one execution of LC, I.e., one set of C source Input. Let's say that the 
following declaration: 

int choice; 

exists in module 1. If module 2 functions need to access this same variable, 
the declaration: 

extern int choice; J 
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would allow the access needed. LC will not reserve any storage for "choice" 
in module 2, since the storage class, "extern", tells LC that storage has 
been reserved in another module. 

The programmer MUST ensure that the declarations are compatible between 
modules. In other words, all "extern" declarations must match the external 
declaration (declaration without "extern") by having the same type, size, and 
amount of indirection. Otherwise, LC may access the variable in incorrect 
ways.. 

The extern statement may also be used to declare what a function returns 
before 1t is defined in the program. This "forward" declaration allows a 
function which returns something other than a signed integer to be defined 
after It 1s used. If the forward declaration 1s not given and a function is 
as -yet-undefined, the compiler assumes that the function returns a signed 
integer. 

STORAGE CLASS - STATIC 



Static objects are stored in declared, fixed memory space. Their 
behavior 1s the same as that of external variables; their scope is more 
limited, however. Static variables declared outside of a function can only be 
accessed by functions within the module being compiled. Other (separately 
compiled) modules cannot get to them by declaring them "extern". Static 
variables declared outside of all functions are accessible to all functions 
within the module. Static variables declared within a function are similar in 
scope to auto* and register variables. They can only be accessed in the block 
in which they are declared. Thus, two static variables with the same name may 
be declared in different functions. 

Functions may also be defined as "static", making them only accessible 
from within the current module. However, since LC is a one-pass compiler, the 
definition of a static function must precede any reference to the static 
function. This is because the compiler assumes that an as-yet-undefined 
function is an external function. 

STORAGE CLASS - DEFAULTS 



When a variable is declared by only stating the storage class: 

auto xl; register x2; 
extern x3; static x3; 

the variable type is assumed to be "int". This is a perfectly acceptable 
shorthand way to make integer declarations. 

When the declaration of a local (declared within a function) variable 
has no storage class, LC assumes that the variable is an auto variable. A 
function declared within another function body is "assumed to have a storage 
class of external. The compiler regards the declaration as if an "extern" 
statement preceded it. 

STORAGE CLASS 
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External declarations which do not have a storage class declared are 
special entities. They belong to the implicit class, "external", and may be 
referenced from other (separately compiled) modules which declare the 
variable as "extern". 
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One of the most powerful features of the C language is its expression 
capabilities. The amount of work that can be done by one expression is 
sometimes mind-boggling. A quick example: 

(end_of_file - (c-getc(f1le))-»E0F)) ? fclose(file) : ++count ; 

This convoluted statement will get a character from a file and place it 
1n the variable, "c". The character is compared to the value "eof" which 
indicates end of file; the result, true or false, is placed in the variable, 
"end_of_file". Finally, if it was the end of the file, the file is ^closed. 
Otherwise, a counter variable, "count", is incremented to provide a cdunt of 
the characters read. 

The example was a bit exaggerated, and expressions this complex can be 
quite hard to understand. Two statements must be made about the complexity of 
expressions in the C language. 

The programmer who does not fully know and use C's 
expression capabilities is seriously handicapped, unable to 
use the full power of the C language. 

On the other hand, a quotation from THE ELEMENTS OF PROGRAMMING STYLE by 
Kemighan and P laugher is appropriate: 

-"Everyone knows that debugging is twice as hard as 
writing a program in the first place. So if you're as 
clever as you can be when you write it, how will you ever 
debug it?" 

The word "maintain" could be substituted for "debug" in the quote above, 
and it would still be valid. You must be able to understand later what you 
wrote into your program. If others are going to have to maintain your 
program, the principle of KISS (Keep It Simple, Stupid) should prevail. This 
is not intended to discourage the use of complex expressions. Just keep in 
mind that the more operators involved in an expression, the more difficult it 
is to properly place parentheses and keep the precedence of operators 
straight. 

There are two kinds of expressions in many computer languages: logical 
expressions and arithmetic expressions. Logical expressions are usually for 
comparing things and for making choices. The result of a logical expression 
is either true or false. Arithmetic expressions result in a number. Usually 
an assignment to a variable is made to save the result of the arithmetic 
expression, or it is passed as an argument. In many language implementations, 
only one type of expression may be used in certain contexts. For instance, 
the BASIC program statement: 

im9 A - ( C <» B ) 

attempts to assign to A the result of the comparison C to B. This is not 

EXPRESSIGMS 
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allowed in many implementations because they are expecting an arithmetic ..— » 

assignment. Even if some BASIC'S allow it, it is best not to do this type of 
assignment, in order to keep programs relatively portable. }•■ 

Another situation is shown in PASCAL: 

If a : a (B < C) THEN BEGIN 

where the PASCAL compiler expects a boolean expression between IF and THEN. 
Even if A is a boolean variable this assignment is not allowed in most PASCAL 
compilers. This is not Intended to denegrate PASCAL. There are good reasons 
why the authors of PASCAL did things this way. However, the C language does 
not draw distinctions between types of expressions within the context of the 
program. The distinctions are made in the types of operators instead. 

PRIMARY EXPRESSIONS 

The elements which are manipulated by operators in an expression are 
called primary expressions. The basic elements which make up a primary 
expression are identifiers, constants, and strings. Identifiers are the names 
of variables and functions. Function and array identifiers effectively 
resolve to the address of the function or array, while all other variable 
Identifiers resolve to the contents of the variable. Constants are character 
or numeric (decimal, hex, octal) values. Strings resolve to the address of 
the first character of the string. 

The operators which LC provides for stating primary expressions group 
left to right. This means that the left-most operator 1s interpreted first. -*' 
The three primary operators supplied by LC are: Isolating parentheses, 
subscripting, and function invocation. 

(expression) /* isolating parentheses */ 
priiaary_expr©ss1on [expression] /* subscripting */ 
priaary~express1on (expression 11st) /* function invocation */ 

ISOLATING PARENTHESES 

When the order in which an expression is to be evaluated conflicts with 
the precedence of operators, the isolating parentheses provide a way around 
the conflict. The expression within parentheses 1s evaluated first, before 
the result of the enclosed expression is used in any expression outside the 

parentheses. For example, when predicting the percentage of up~t1ma for any 

equlpsssent, the following foraula Is used: 

MTBF 

availability * — — — — — 

MTBF * fflJR 

MTBF * mean time between failures 
MTTR ■ mean time to repair 



When writing this formula into a C expression a conflict occurs because the 
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division operator takes precedence over the addition operator. If the 
expression is written like this: 

up_t1me » mtbf / mtbf + mttr 

the result will always be mttr plus one. This is because the division is done 
before the addition. To avoid this, the expression can be stated as follows: 

up_t1»e ■ nitbf / (mtbf + mttr) 

to achieve the correct result. 

Parentheses can be used on either side of an assignment operator. At the 
risk of confusing the reader with as-yet undefined operators, we nevertheless 
provide an example using pointers. In certain cases during the use of pointer 
arrays, indirection must be performed before subscripting into the data item. 
Since subscripting takes precedence over Indirection, this kind of expression 
must be written as follows: 

example(arg) 

char *arg[]; /* pointer to a char pointer array */ 



{ 



/* wrong way - accesses third pointer */ 
/* instead of third character. */ 



•^ *argC3] ■ ; 



) 
SUBSCRIPTING 



/* right way - zero's the third character of */ 
/* first string */ 

(*arg)[3] » ; 



Subscripting 1s denoted by a subscript in brackets following a primary 
expression: 

pr1mary_express1on [subscript] 

If the primary expression is an array name, or a pointer to an array, the 
subscripted expression returns the element denoted by the value of the 
subscript. C arrays are subscripted from zero, i.e. the first element in an 
array is numbered zero. 

Function identifiers may not be subscripted. A primary expression 
denoting an array of pointers to functions may be subscripted. The primary 
expression must indicate the size of the object being subscripted (char, int, 
pointer) or the subscript will produce an error message. For example: 

x - 25C3]; 
is invalid. 
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FUNCTION INVOCATION 



A primary expression followed by parentheses will cause the function 
denoted by the primary expression to be called,, Arguments may be passed to 
the invoked function by placing them in the parentheses, separated by 
comma's. LC is yery liberal about the primary expression. ANY valid primary 
expression can be invoked as a function, regardless of the type of the 
primary expression. Thus, it is perfectly acceptable to write: 

(0x11060)0; 

to call the function at hex location 0060 (This would call the GPAUSE routtRfi 
1n the TRS-80 ROM). 

Any number of arguments can be passed to the called function. Care must 
be taken that the number of arguments passed is the number that the function 
expects. Otherwise unpredictable behavior may result (certainly not correct 
behavior). If a variable number of parameters must be passed, then a control 
indicator must be passed to tell the called function how many arguments there 
are (for example, the fprintfO and printfO functions in the standard 
library). All arguments listed in a function invocation must appear on the 
same line in the LC source file. This is not a limitation imposed by the C 
language, but by the LC implementation. Arguments can be -any valid LC 
expression, including other function calls. The arguments are evaluated from 
right to left, i.e., the right-most expression is evaluated first. The 
programmer should not rely on this order of evaluation since some other 
implementations of the C language evaluate them left to right. Statements 
like this one: 

funk( arg-H-, arg2Earg3 ); 

will cause different elements of arg2 to be passed to funkO when different C 
compilers are used. Stay away from this sort of trickery if you can. 

UNSUPPORTED PRIMARY EXPRESSIONS 

The primary operators, "." and "->", which are used with structures and 
unions are not supported (structures and unions are not supported either). 
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"^ 



UNARY OPERATORS 



Unary operators operate on one object (hence the name). If more than one 
unary operator operates on the same object, the operators are evaluated right 
to left. The unary operators supplied by LC are: 



& 



OPERATOR OBJECT 



expression 

lvalue 

expression 

expression 

expression 

lvalue 

lvalue 



DESCRIPTION 



indirection, 

means "object at..." 
pointer, 

means "address of..." 
negates the expression, 

"minus expression" 
logical complement, 

"not expression" 
one's complement 

of expression 
increment and save 

in lvalue 
decrement and save 

in lvalue 



*? 
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All unary operators must appear before (prefix) the object, except the 
increment and decrement operators. The "++" and "— " may appear after 
(postfix) the object also. The term "lvalue" means an expression which 
evaluates to the address of a data element or pointer field. Constants, 
function identifiers, and array names are not lvalues. The term derives from 
the observation that "lvalues" are the only expressions allowed on the left 
side of an assignment expression. 

• *• 



The indirection operator can only operate on a pointer expression. Its 
meaning is effectively "object at ..." The address contained in the pointer 
is the address of the object referred to by this type of expression. For 
example, 

seejjointer (pointer) 

char *pointer; /* a character pointer */ 
{ 

/* first print the address passed in pointer */ 

printf( "address is: %d ".pointer); 

/* now print the data at that address */ 

printfC'data is: Xd ", *pointer); 



> 

will print both the address (contents of the pointer 
at that address (result of the indirect expression). 



variable) and the data 
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This unary operator effectively means "address of..." or "pointer 
to...". It evaluates to the address of the lvalue it precedes. 



When the unary negation operator precedes an expression, the result is 
the two's complement negative of the value of the expression.. When the '-' 
precedes an unsigned or pointer expression, the one's complement of the value 
is taken. Since all expressions in LC are evaluated using 16-bit arithmetic, 
the expression is negated for the full 16 bits. *? 

1 1 a 

The unary logical complement operator, or "not" operator evaluates to 
false if the expression is true and to true, if the expression is false. False 

Is defined as and any non-zero value is considered to be true» Hosever» ill 
LC operators which result in true or false use one (1) as the value for true. 
Thus, the least significant bit of the result indicates true or false. 



The one's complement operator Inverts every bit in the expression. No 
regard is given to the type of the expression. 

sa <bb <s» «• «s» ob «■> <■» «a» *n 

The incranent and decrement operators may be used either before (prefix) 
the operand or after (postfix) the operand. The operand must be an lvalue or 
lvalue expression. In either case the contents of the lvalue is incremented 
or decremented and stored back into the lvalue. The difference between prefix 
and postfix is whether the result of the expression is Incremented or not. 
Prefix means that the value after the increment or decrement is the result of 
the expression. Postfix means that the value returned by the expression is 
the value before the increment or decrement. 

UNSUPPORTED UNARY OPERATORS 

The "(typejname)" and "sizeof" operators are not implemented in LC. 



.i\ 
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BINARY OPERATORS 



Binary operators act upon two expressions together. The type of the 
result depends on the type of the two expressions. If the type of any of the 
expressions is "char", "short", or "long", it is treated as an integer. If 
one expression is unsigned, the other expression is treated as unsigned as 
well, and the result 1s unsigned. If one expression only is a pointer, the 
result of the expression is a pointer of the same type. If both expressions 
are pointers, the result 1s unsigned. 

When several binary expressions are concatenated together (without 
isolating parentheses) the order in which the binary expressions are 
evaluated depends on the precedence of the operators in the expression. In 
the expression, 

a + b * c 

the evaluation of "b * c" precedes the evaluation of the addition, since 
multiplication has a higher precedence than addition. The expression is 
evaluated like this: 

a + (b * c) 

As previously described, isolating parentheses can be used to change the 
order of evaluation. To have the addition performed first, the expression can 
be written: 

(a +~b) * c 

Each class of operands is described below in order from the highest 
precedence to the lowest. Note that when all the operators in a complex 
expression have the same level of precedence they are evaluated in a certain 
order; right to left or left to right. It can be said that a class of 
operators "group" left to, right, or right to left. If the order of evaluation 
between like operators does not matter, the operator is said to be 
associative. Here is an example of how the order of evaluation affects an 
expression: 

a / b / c / d 

This expression 1s evaluated a follows: 

(((a / b) / c) / d) 

Thus, the division operator is said to group "left to right". 



BINARY OPERATORS 

? - 19 



LAN6UAGE DEFINITION 



PRECEDENCE OF BINARY OPERATORS 
(Highest to lowest) 



MULTIPLICATIVE OPERATORS 
expression * expression 
expression / expression 
expression % expression 

ADDITIVE OPERATORS 
expression + expression 
expression - expression 

SHIFT OPERATORS 
expression « expression 
expression » expression 

RELATIONAL OPERATORS 
expression < expression 
expression > expression 
expression <» expression 
expression >■ expression 



- group left to right 

multiplication 

division 

modulus (remainder) 

- group left to right 

addition 
subtraction 

- group left to right 

shift left 
shift right 

- group left to right 

less than 
greater than 
less than or equal to 
greater than or equal to 



EQUALITY OPERATORS 
expression •■ expression 
expression I* expression 

BITWISE AND OPERATOR 
expression !■ expression 



- group left to right 

equal to 
not equal to 

- associative 

bitwise and 



BITWISE EXCLUSIVE OR OPERATOR - associative 
expression * expression bitwise exclusive or 

BITWISE INCLUSIVE OR OPERATOR - associative 

expression | expression bitwise inclusive or 



LOGICAL AND OPERATOR 
expression && expression 

LOGICAL OR OPERATOR 
expression II expression 

m m m m m mm m m m mm* 

CONDITIONAL OPERATOR 
expression ? expression : 



- groups left to right 

logical and 

- groups left to right 

logical or 

- groups right to left 
expression 



ASSIGNMENT OPERATORS - group right to left 
lvalue ■ expression simple assignment 

lvalue <op>« expression compound assignment 
(<op> is any binary operator except logical, 
relational, or conditional operators) 



rt 
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The multiplicative operators take precedence over all other binary 
operators and group left to right. When the result of multiplication 
overflows 16 bits, the left-most (high-order) bits are truncated. Since 
integer division is used, the fractional portion of the result is lost. The 
result of division is always truncated toward zero. The modulus operator 
returns the value of the remainder in the integer division of the two 
expressions. 



The additive operators result 1n the addition or subtraction of the two 
expressions. In subtraction, unsigned subtraction only takes place when both 
expressions are unsigned. If one of the expressions is a pointer and the 
other is not, the other value 1s adjusted to reflect the size of the object 
pointed to. Thus, if "p" is a pointer, "p + 3" returns the address of the 
fourth object pointed to by "p". If p points to integers, then LC 
automatically doubles the offset to account for the two-byte elements. 



• ••• 



The shift operators shift the left-hand expression by the number of bits 
indicated in the right-hand expression. Zeroes are shifted 1n to replace the 
bits shifted out. If the right-hand expression is negative or zero, no 
shifting takes place. If the right-hand expression 1s 16 or more, the result 
is always zero. 



Relational operators result in a true (1) or false (0) value, depending 
te indicated condition. 



on the indicated condition. 



The equality operators, "equal" and "not equal", respectively also 
return true (1) or false (0) depending on the two expressions' equality. 



The bitwise AND operator does a bitwise AND with the two expressions. 
Each bit position in the result will be set to be one if and only if both 
corresponding bits in the expressions are equal to one. This is useful for 
isolating individual bits within a word by using a "mask" as one of the 
expressions. Any bit in the mask which is set to zero will cause that bit in 
the result to be zero. Any bit set to one will cause the bit in the other 
expression to remain the same. 
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The bitwise exclusive OR operator. Each bit in the result of an 
exclusive OR is set only if the corresponding bits in the expressions are 
opposite, i.e., 1 and 0, or and 1. If they are the same, that bit in the 
result will be zero. This can be used to complement bits, using a "mask® 
expression. Any bit which is 1 in the mask will cause the corresponding bit 
of the other expression to be complemented in the result. Any mask bit which 
is $ will pass the corresponding bit unchanged Into the result. 

*! 8 

The bitwise inclusive OR operator. Each bit in the result will be set to 
1 if either of the corresponding bits in the expressions are equal to 1. This 
can be used to set any particular bit in an expression to one by using a 
'mask" expression. If a bit in the mask is equal to 1, then the corresponding 



bit in the result will be set to X. 
that bit in the result will be 
manipulated. 



• «• 



If a bit in the mask is equal to 0, then 
the same as in the expression being 



The logical AND operator results in a true (one) or'false (zero) 
condition, depending on the relationship of the two expressions. The result 
is true only if both expressions are true (non-zero). Moreover, if the first 
expression 1s false, the second 1s never evaluated. 

'W 

The logical OR operator returns a true (1) result If either of the 

expressions is true (nen*i§ro)» If the first expression 1s true, the second 
expression 1s not evaluated. 



The conditional operator gives the C expression repertoire the 
equivalent of an 1f-then-else construct. It can technically be classified as 
a binary operator since only one of the last two expressions Is evaluated. 
The first expression 1s evaluated as true (non-zero) or false (zero). Then, 
1f the first expression was true (non-zero), the second expression is 
evaluated as the result of the expression. Otherwise, 1f the first expression 
was false (zero), the third expression 1s evaluated for the result. The 
conditional operator groups right to left: 

a?b:c?d?e:f:g 



is evaluated in the following manner: 
alb; (cj <d ? @ : f) : g) 



J 
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> Either or both of the second and third expressions can contain conditional 

expressions. 

•««, •+««, •-»', •*»', V" 1 , *S»', '««', •»■', •*■*, '"-', '|"' 

The assignment operators place the result of the right-hand expression 
into the object denoted by the left-hand expression, after performing the 
indicated operation with the contents of the lvalue when an assignment 
operator other than '*' is used. The simple assignment, '■', places the 
result of the right-hand expression unchanged into the object denoted by the 
left-hand expression. The compound assignment operators have the form: 

expression^!. <op>« expression^ 

and 1s evaluated like this expression: 

expression^! * expression^! <op> expression^ 

The first form is more efficient since expression^ only need be evaluated 
once. 



A 
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LC STATEMENTS 



LC statements are used to specify the action to be taken by the program. 
The statements given in the program are executed one after the other. Certain 
statements (conditional and looping statements) will direct the order of and 
conditions for execution of other statements. Some definitions of statements 
in the following text require that a substatement be included in the 
statement. Any place where a substatement is required there may be one simple 
statement or more than one statement combined in a compound statement. 

SIMPLE STATEMENTS 



<*■: 



Simple statements are of three types: expression, declarative, and 
control. The declarative statements are described fully 1n the previous 
sections on functions and variables. The type, size and scope of functions 
and variables are declared in declarative statements. 

A simple statement always ends with a semicolon. The semicolon is the 
STATEMENT TERMINATOR. It is not a statement separator as in the PASCAL 

iaiigU* it. la umajj tfgqulrgQ aw Ui@ cnu Ut m Simpic Sbausilienip. 

COMPOUND STATEMENTS 

The left and right brace characters, "{"and "}", are used to indicate 
the beginning and end (respectively) of a compound statement; A compound 
statement, also called a block, can be used anywhere that a simple statement 
may be used. Thus, wherever LC's syntax requires a statement, more than one 
statement may be given by enclosing them 1n braces. Within the compound 
statement there may be any combination of simple and compound statements. 

The compound statement has the format: 

{ <declarations> <statements> > 

No declarations or statements are required, although the use for an 
empty block would be as a null statement of sorts. The declarations should 
appear before any statements. Any of the statements may 1n turn be another 
compound statement. No semicolon 1s required after the compound statement. 

The only place where a compound statement 1s required instead of a 
simple statement is 1n the body of the switch-case statement. The body of a 
function 1s one compound statement. Here are some examples of compound 
statements: 

funcO 

{ /* the body compound statement */ 
a a b; /* simple statement */ 
if (a>c) 

{ /* another compound statement */ 
c»a; 
b*a; 

STATEMENTS 
2 - 24 



*N 



J 



LANGUASE DEFINITION 

} /* end of compound statement */ 
return a+b+c; 
> /* end of function body compound statement */ 

NULL STATEMENT 

A null statement is a sort of place-holder. LC requires that a statement 
be given in certain places. If no action is needed in the place required then 
the null statement can be used. No action is taken by the null statement. 

The null statement is simply a statement terminator (semicolon) by 
itself, with no preceding statement. 



y-j 



null() 

{ /* do-nothing function */ 

; /* a null statement */ 
} 



EXPRESSION STATEMENT 

An LC expression followed by a semicolon is called an expression 
statement. The expression is performed when it 1s encountered. LC will allow 
an expression that has no assignment in an expression statement, even if it 
does nothing. Expression statements are used to assign values to or modify 
values of variables, or to Invoke functions. Some sample uses of expression 
statements: 

retcode ■ call__funct1on() ; /* call a function */ 
a«b»c*07 /* make a, b, c equal to */ 
++counter ; /* increment a counter */ 

IF STATEMENT 

If (expression) statement 

If (expression) statenent 
else statement 

The "if" statement gives the programmer the capability to decide whether 
a statement will be executed. The criterion for the decision is the result of 
evaluating the expression. The expression may be any valid LC expression. If 
the expression evaluates to true (non-zero), then the statement is executed. 
If the expression evaluates to false (zero), then the statement following the 
"else" (if any) is executed. 

"If" statements may be nested, i.e., the statement within an "if" 
statement may be another "if" statement. Too much nesting of "if" statements 
can be hard to follow, so moderation is advised. 
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Some examples of "if" statements: -^ 

If (x < 0) x • -x ; /* absolute value of x */ % 

if (iO0) { i*x; b»a; } /* compound statement */ 
else — i; /* and an else clause */ 

/* nested if statements */ 
if (past_twe1ve) 

{1f""(before_six) say ("good afternoon"); 

else say("good evening");} 
else say("good morning"); 

SWITCH-CASE STATEMENT 

switch (expression) < <sw1 teh_$tateiignt> ... } 

switches tatenent * statement 

""" case consta«t_express1on : 

default : ~ 

The switch-case statement allows program execution within the 
<swi ten statement to be determined by the case and default prefixes. The 
expression in the switch statement 1s evaluated first, then, 1f any of the 
cons tan t_express Ions match the result, execution begins Immediately past that 
case prefix. If none of the cases match the result and there 1s a default " ^ 

prefix, then execution begins at the default prefix. Otherwise, when no }s 

matching case is found, no statements in the sw1tch_statement are executed. 

The switch-case statement MUST have a compound statement as its 
substatement. This Is the only case where this is true. The default and case 
statements may occur in any order within the body of the switch-case. 
However, A CASE OR DEFAULT MUST PRECEDE THE FIRST STATEMENT in the 
switch-case. If this is not done, none of the cases will ever be executed (LC 
limitation). [LC 1.0a requires that the "default" must be the last prefix in 
the switch-case-default construct.] 

The break statement is used to exit the switch statement. 



break; 
case april: case June: case november: 



switch (month) 

< case January: case October: case december: case July: 
case august: case march: case may: 

days ■ 31; 
case September: 

days » 30; break; 
case february: 
{ If (leap__year) days • 29; 

else days * 28; 

break; 
> 
default: days * 0; error ■ true; 
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WHILE STATEMENT 

while (expression) statement; 

The most basic form of looping is provided in LC by the "while" 
statement. Simply stated, while the expression results in a true (non-zero) 
value, "statement" (also called substatement) is executed. The expression is 
evaluated before each time the substatement is executed. Therefore, the 
substatement may be executed from zero to any number of times depending on 
the expression. 

If more than one simple statanent must be placed in the loop 
substatement, then the substatement must be a compound statement. The break 
statement can be used to exit the loop from within the statement. The 
continue statement can be used to continue directly on to evaluate the 
expression, skipping, the rest of the substatement, from anywhere within the 
statement. 

while (driving) watch(the_road); 

while (jogging) 
{ take(a_step); 

breatheO; 

1f (too tired) break; 
} 

00 STATEMENT 

do statement while (expression) ; 

"Do" differs in only one way from the while statement - the expression 
is evaluated after the statement is executed. Therefore the substatement will 
always be executed at least once. The substatement will be repeatedly 
executed until the expression evaluates to false (non-zero). 

do anythingO; 

while (there^is^still^time) ; 

/* shuffle routine */ 

do 

{ cut_the_cards(); 

shuffleO; 
} 
while ( ! ready_tq_deal ) ; 
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FOR STATEMENT 



for ( expr_l i exprJ2 ; expr_3 ) statement 



The for statement is a looping statement which provides a convenient 
place for initializing, testing, and incrementing loop control variables. The 
format shown above can be rewritten using the while statement: 

exprJL ; 

while" ( expr__2 ) 
{ statement 
expr.3' ; 



} 



*? 



ExprJ. 1s evaluated once before the loop is entered. The test 
expression, expr 2, is evaluated before each execution of the sub statement. 
If 1t results 1n""a false (zero) value, the loop is not executed and execution 
continues to the next statement. Expr_3 is evaluated after each time the 
substatement is executed. ~ 

Both exprjl and expr_3 can be more than one expression, separated by 
commas. ExprjT can only be one expression and should result in a logical 
value. 

Due to limitations of the LC Implementation, all three expressions in 
parentheses must be on the same line. 

for ( c ■ *A* s c <» 'Z' ; ++e ) 

putchar(c); /* print the letter */ 
/* "Now I've said my ABC's ..." */ 

BREAK STATEMENT 

break ; 

Break is used to exit any "while^ "do", or "for" loop and to exit the 
body of a "switch" statement. Whenever a break statement Is encountered, 
execution Immediately goes to the next statement past the loop or switch 
statement. Break is Illegal outside of any loop or switch compound 
substatement. For an example of the use of break "in a switch statement, see 
the section on switch-case above. 

strscan(c„s) 

char c,*s; 
{ /* find character c in string s */ 

while (*s 1* c) 

{ If (*s — 0) break ; /* end of string */ 
++s ; /* next character */ 

} 

return s ; 
> 
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CONTINUE STATEMENT 



continue ; 

The continue statement is used to skip the remaining statements in a 

compound loop substatement. In a "while" or "do" statement, execution 

continues at the test expression. In a "for" statement, execution continues 

at the reinitializing expression (the third expression). The continue 

statement is illegal outside of any loop statement. 

/* convert to lower case */ 

while ((c ■ getcharO) !« eof) 

{ 1f ( c < 'A* II c > 'Z' ) /* not an uppercase character */v 

continue ; /* doesn't apply */ 

c » tolower(c) ; 

putchar(c) ; 
} 

RETURN STATEMENT 



return ; 

return expression ; 

~n The return statement causes the currently executing function to end. If 
an expression 1s provided, then the result of the expression is returned as 
the value of the function. The returned value is undefined if no expression 
is provided in the return statement. The return statement is not required to 
return from a function. When no statements are left (the bottom of the 
function body is reached), the function automatically returns as if a return 
statement with no expression were encountered. Return statements are needed 
when a value must be returned or when the return must take place before the 
end of the function. 

square (num) 

/* square a number */ 

{ return num * num ; } 

getHne(buf) 

char bufG ; /* line input buffer */ 



{ 



/* check for a valid file pointer */ 

if (file pointer »» NULL) 

{ bufl0] » '\0' ; /* put a null string in buf */ 

return ; /* back to caller */ 
} 
fgets(buf, bufsize, filejsointer); 
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GOTO STATEMENT 

goto label; 

The goto statement causes an unconditional branch to the statement 
identified by label. The labeled statement must be contained in the current 
function. It 1s Illegal to attempt a goto to a statement 1n some other 
function. An attempt to do so will result in an error during the assembly 
phase. The following example Illustrates the use of goto (note: it is 
strongly recommended that you avoid the use of the goto statement): 

rest(time) 
int time; 

if ( time > 2300 ) goto sleep; 
else return; 

sleep: for ( ; ; ) 

9 

> 

LABELED STATEMENT 

libel: statement; 

Any statement can be prefixed with a label. This construction is usually 
used to target the argument of a "goto" statement. The format of a label is a 
valid identifier followed by a colon. The following are labeled statements: 

calculate: 1 +• 10; 

bigblock: i«j»k»l»m»n*o a p»0; 
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LC takes C source code as input and generates an EDAS Version IV 
compatible assembler source file as output. Thus the output of the 
compilation process must be assembled and linked with any required run-time 
library module before 1t can be executed. The assembly and linking process 1s 
performed using the EDAS IV assembler. A Job Control Language (JCL) file, 
"LC7JCL", is provided to present the compilation and subsequent assembly as a 
job stream to the operating system. The JCL procedure requires minimal entry 
of commands by the programmer to create an executable CMD file. The JCL file 
1s: 

. Batch creation of a runnable ELSIE program. n 

. Format Is: do lc (f1le«<progname>,{show}) 

//1f show 

lc #f1le# +1 

//else 

lc #file# 

//end 

edas (jcl, abort) 

lie 

c/cprogram/#file# 

//1f show 

a#file# -we 

//else 

a#file# -nl 

//end 

b - 

. completed compilation 

If you want to compile a program called "myprog" and generate the finished 
CMD file with only one statement, then the command: 

DO LC (FILE-MYPR06) /* See ATTENTION on page 3-11 */ 

lets you sit back and relax while the machine does all of the work. If the 
/ASM and /CMD files do not already exist, you may want to enter a drive 
specification as follows: 

DO LC (FILE-MYPROfi:l) 

which looks for input and places output on drive one (1). 

The first stage of the LC language process is, of course, to create an 
LC source file. The editor that is a part of EDAS IV is provided for this 
purpose. In order to use EDAS for the creation and maintenance of LC source 
files, execute EDAS with the command: 

EDAS (LC) 

The EDAS manual should be consulted for all operations concerning the editor 
or assembler functions. 
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The second stage of the LC process is the compilation of the LC source 
using the LC/CMD compiler. Use the JCL procedure shown above. However, if you 
want to take direct control of the operation, you can execute LC directly. LC 
is executed when a command line beginning with LC is typed at the "DOS ready" 
prompt or encountered in a XL file. The format of the command line is 
free-form - simply a list of input file specifications and option switches. 
The command syntax is as follows: 



LC filespec {filespec...} {switch} {switch...} 

filespec - A file specification for the input f1le(s). ' n 

A maximum of 8 filespecs may be passed. 

switch - Represents an optional compiler switch(es) 
These switches are preceded with either a 
plus sign (+ ■ on) or a minus sign ( - * off). 

asaBSB>B«aa«saasatM*iis*saiiaasasa«s«>ssss>an>aaiaa«uauiM«aB 

The compiler is executed by entering a command line such as: 

LC CPR06RAM;2 +LIST 

which compiles the LC source file, "CPROGRAM/CCC", and generates the output 
file, "CPRQGRAM/ASM", on drive 2. The "+LIST" switch specifies that you want 
the LC source code listed to the screen during the compilation process. 

The switches allow the user to control certain features of the compiler. 
Switches and filenames may be intermixed in any order on the command line. 
The simplest compilation command would simply be "LC PRQGNAME" which compiles 
the file, "PROGNAME/CCC", and generates the output file, "PROGNAME/ASM". 

FILE SPECIFICATIONS 



- 1 



There may be up to eight Input file specifications given on the command 
line. They are processed by the compiler 1n the order they occur (left to 
right). If no extension is given for a source file, the default extension 
"/CCC" 1s assumed. It is recommended that you establish your LC source files 
with this file extension for uniformity and standardization. If you use "EDAS 



(LC)" for your LC source code 
automatic. 



maintenance, the use of the /CCC extension is 



The output file specification defaults to the same name as the first 
input file specified. LC will append the file extension "/ASM" to this name. 
The drive specifier, if any, of the first Input filespec is used as the drive 
specifier of the output file. The drive specifier should be given if the 
output file must be written to the same drive as the input file. The LC 
OUTPUT option may be used to specify a different file name or change the 
destination drive number. Assembler source code output may be suppressed by 
turning off the OUTPUT option* This csn !»c helpful for Quickly cimckifiQ 



J 






OPERATOR eUIDE 



) 



'^ 



syntax without generating an output file. 
COMPILER SWITCH OPTIONS 



Compiler option switches are turned on or of f by a •+• or '«', 
respectively, followed by the name of the switch. For example, "+list" causes 
the LC source code to be presented to the standard output device during the 
compilation. The compiler regards any command line argument not beginning 
with a plus or minus as an input file specification. Only the first letter of 
the switch is examined, so partial spelling (or misspelling) is accepted. 
Certain switches have operands which are specified by following the option 
name with '■' and the operand. For Instance, •*+output«myf1le:3" will cause 
the output by the compiler to be written to "MYFILE/ASM" on drive £? Instead 
of the filename that would have been the default. 

COMMENT 



This switch controls whether the original LC source code will be written 
to the assembler output file as comments. The normal default is ON. The 
C-source appearing as comments may be instrumental in your understanding the 
compiler output as it generates a minimally commented assembly source 
program. 

GLOBAL 



GLOBAL controls the definition of external variables. If the switch is 
turned off, ~ variables declared external are not defined in the assembler 
output. If turned on, external variables are defined in the assembly module 
output. This switch defaults to on. For more information on using the GLOBAL 
option, see the ADVANCED TOPICS chapter. 

LIST 

The standard output would normally receive minimal feedback during the 
compilation process. If the LIST option is turned off, LC will write each 
function name followed by a period representing each statement in the 
function. An example of this is: 

mainO { }. 

. moveO { }. 

min() {....}. 
max() {....}. 

P<> { }. 

No errors found 

If you want to see the source code as LC is compiling, you must specify the 
-+1" option, since the default is "-LIST". Note that since listing output is 
to "standard output", it is subject to I/O redirection. Thus, if you want a 
printer listing, for whatever reason, you could specify ">*PR M in the " LC 
command line. 
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OUTPUT^SPEC 

This switch controls the output of the compiler to the output file. If 
the switch is off, no output file is generated. However, if it is on, but no 
SPEC is given, LC appends "/ASM" to the name of the first input file in order 
to create the output file specification. When a file specification is given 
for SPEC, it becomes the name given to the output file. A default extension 
of "/ASM" is inserted 1f no extension is given. If only a drive specification 
(":D") is given, the output file is written to that drive, with the same file 
name as the first input file. This switch defaults to on with no SPEC. 



PAUSE 



^ 



When this switch is on the compiler will stop when any errors are found 
and displayed. Any key except BREAK will continue compilation. BREAK will 
abort the execution of the compiler at any time if this switch is on. If LC 
was invoked from JCL, the JCL will also be aborted. This switch defaults to 
on. 
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CREATIN6 A CMO FILE 



Once the LC compiler has compiled your program into assembly language, 
you need to use the EDAS assembler to create the CMD file. In order to 
provide the proper initialization in the CMD file and ensure that all 
necessary runtime routines are linked with your program, a special assembler 
file, LC/ASM, has been provided. A listing of the file follows to aid 1n 
Illustrating its functions: 

LC/ASM - 09/09/82 

This module is assembled to create the 
run-time /CMD program file. The line: 

*GET CPR06RAM 
fetches the file containing your "main" 
program compiled by LC. Separately 
compiled C-source modules can be fetched 
by adding additional *GET statements. 
If you have created a user library(ies), 
add additional *SEARCH statements. 



• *8*a* 



COM '<LC is copyrighted (c) 1982 by Jim Frimmel> 



ORG 


5200H 




©START: LD 


HL,(4049H) 


;P/u Model I HIGHS 


CALL 


@MOD13 


;Test for Model I/III 


JR 


NZ,$+5 


;Go if Model I 


LD 


HL,(4411H) 


; else use Ill's 


LD 


SP,HL 


;Set stack area 


CALL 


@GO 


;Initial1ze 


CALL 


MAIN 


; Execute user prog 


LD 


HL,0 


;Set return code 


PUSH 


HL 




CALL 


EXIT 


;Back to DOS 


SSSTEMP DEFL 





;Init relative storage 


♦GET LCMACS 




;Get macros used by LC 


*GET CPROGRAM 




;Fetch user program 


IF 


0JNLIB 


;True if #option inlib 


♦SEARCH IN/LIB 




{Installation lib? 


END IF 






IF 


© FPLIB 


;True if #option fplib 


@ FPLIB DEFL 


e_FPLIB.OR.FPINIT 


;Force GET of fpinitO 


♦SEARCH FP/LIB 






END IF 






♦SEARCH LC/LIB 




; Standard lib alwaysl 


SSSTORG EQU 


$ 


;Set to 1st storage byte 


$PR0GEND DEFL 


$$STORG+$$STEMP 


{Establish program end 


END 


©START 





y*^ 



The LC/ASM file provides a front end that makes your program usable on either 
a Model I or Model III. This is the file that is assembled. Notice that the 
bulk of the resulting CMD program is assembled from files via the ♦GET 
statement and *SEARCH statements. If you have not yet read chapter five of 
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the EDAS manual, you may want to temporarily turn to the sections on *GET and 
*SEARCH located within the fifth chapter. ] 

J 
If your compiled program file was named MYPROG/ASM, it is linked into 
LC/ASM by changing the statement U *GET CPROGRAM" to "*GET MYPROG". This is 
done simply with the EOAS editor or is automatic when using the LC/JCL Job 
Control Language "hands-off" procedure. 

For a great deal of your programs, the only LC runtime routines needed 
will be located in the LC/LIB library. Since all LC programs need some of the 
routines in LC/LIB, that library is ALWAYS searched during the assembly 
process. The floating point library, PP/LIB, will be automatically searched 
if your program requested the floating point library search via an "#option 
fplib" compiler macro. This 1s explained 1n more detail in the LC LIBRARIES 
chapter. 

Many useful routines are stored in the installation library, IN/LIB. 
This library is not normally searched in order to save you assembly time when 
you need not refer to the IN/LIB routines. However, 1t 1s wery easy to force 
an automatic search of the Installation library. All you need to do is 
specify an "#©pt1on in] lb" compiler micro In your LC source program (similar 
to "foption fplib"). For example, 

Unclude stdlo/csh 

foption hilib /* This statement Invokes *SEARCH IN/LIB */ 
mainO 

1nt dot; - , 

{ for ( dot*0 9 dot < 128, dot++ ) .. / 

set( dot, 9 )i 
@xit(0); 
} 

will schedule the compilation and assembly of your program with a forced 
search of the installation library (to resolve linkage to the "setO" 
function. 
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COMPILER DIRECTIVES 



The LC compiler supports a handful of directives that control various 
aspects of the compiler during the compilation process. One of these 
directives, "#include filespec", you will quickly become familiar with. 
Others may he used less frequently. They, nevertheless, provide additional 
power in the use of the LC language "system". These directives are: 



#include 



finclude <filespec> 



/*■} 



This directive tells LC to Insert the file designated by "filespec" into 
the source stream being compiled. The <filespec> will default to an extension 
of /CCC if no extension is given. The #include is used quite frequently to 
merge the STDIO/CSH standard header file into your compilation. An 
illustration of its use is: 

/* sample program to illustrate ^include */ 

#include stdio/csh 

main() 

{ 

int x; 

x- -3 +4*5- 6; printf ("%d\n",x) 



^ } 

#define 



u 



#def1ne <macnawe> <def1n1t1on> 

The "define" directive is a macro definition. It creates a macro, called 
macname", which is defined to be the string of characters following the 
macname (the definition). The compiler will substitute the string wherever 
"macname" is found in the LC source stream. It is strongly recommended that 
macro "macnames" be defined in upper-case characters so that it becomes 
distinct when looking at your source code. 

<macname> must be a valid LC identifier, whereas the <definition> is 
anything and everything up to a comment or the end of the line. The 
<defin1tion> 1s substituted whenever the <macname> is encountered in the LC 
source code input past the #define of <macname>. 

An example of the use of #define follows: 

#1nc1ude stdio/csh 

#define PRINTX printft"%d\n",x) 

mainO 

< int x; 

x« -3 +4*5- 6; PRINTX; 

x-3+4%5-6; PRINTX; 
> 

M 
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#opt1on 



#opt1on <optname> {value} 

The #option directive is used to pass symbol definitions from the LC 

source code to the assembly phase. The <optname> must be a valid LC. 

identifier. Value must be a numeric or character constant. Escape sequences 
may be used in the constant. The compiler translates the #option directive to 
the form: 



NAHE 



DEFL value 



The "value" is optional (as shown above by apearing within braces). If the^ 
value is omitted, the DEFL statement will default to a value of negative one 
(-1). This indicates TRUE to the EDAS assembler. 

The #opt1on directive is used in LC to Invoke a search of the 

installation library, IN/LIB, or the floating point library, FP/LIB. If your 

application will be using functions in either library, you will need to add 
the statement(s): 

#option FPLIB 
#option INLIB 

for the floating point and Installation libraries respectively. 

LC has reserved additional option names for use with the #option 
directive. These are: 

MBS - specifies that your program {w1ll}/{w1ll NOT} 

be using command line arguments (argc, argv). 
LC will suppress the run-time code normally 
used to process arguments thus reducing the 
size of your CMD program. 

FIXBUFS - specifies pre allocation of buffer space for 
standard I/O. 

KBECHO - specifies echoing of keyboard Input 
to the video display when Inputting 
from a file opened with fllespec, "*KI". 

MAXPIIES - specifies the maximum number of concurrently 
opened files permitted. 

REDIRECT - specifies that your program <w1ll}/{wm NOT} 
be using standard I/O redirection (>, <, #). 
LC will suppress the run-time code normally 
used to process I/O redirection thus reducing 
the size of your CMD program. 

For additional information on the use of these options and "foption" in 
general , read the section- on options jo the ADVANCED TOPICS chapter. 
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#asm - lend asm 



#asn 

transparent assembly language code 

fendasn 

The directive pair, #asra - #endasm, can be used to insert assembly 
language source code directly within the LC source file. It should be used 
ONLY when it is ABSOLUTELY necessary to write a routine in assembly language. 
Remember, any LC source code file that has imbedded assembly language Cede is 
generally NOT portable. The more assembly language code you imbed, the less 
portable your programs become and the more you have to recode when 
transporting your program to another machine. 

All input past the #asm statement is passed unchanged into the output 
file. Of course, since the output file is an assembly language source file, 
the statements following the "lasm" should be assembly source statements. The 
block of assembly statements is ended with the #endasm statement. Please 
note: the M #endasm" statement must be the first thing on a line, other than 
tabs and spaces. Otherwise the "#endasm" will not be recognized and the C 
source code following the "#endasm" will be passed uncompiled to the output 
file. 

This escape to assembly language is provided as a convenient kludge 
mechanism only. It is not intended to be the normal way of interfacing 
assembly language functions to a C program. The proper way to interface to 
assembly language is to place the assembly function in a separate module, 
perhaps even in a user library if it is to be used frequently. This makes the 
program easier to transport to other systems, as the machine-dependent code 
is separated from the program source. See the Advanced Topics chapter for 
more information on assembly language programming in the Elsie environment. 
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A SIMPLE EXERCISE 



It may prove helpful to you to see a program generated from start to 

finish. It will be a small one, but nevertheless, one that will exercise all 

of the steps needed to accomplish the creation of a CMD file. If you have 

ever entered and/or edited a BASIC program, you are ready to perform this 
exercise. Before we begin, remember that you will need the LDOS keyboard 

driver activated. A few of the extra keyboard characters will be needed. It's 

probably a good idea to refresh your memory as to the key combinations. 

character key combination 



c 


CLEAR-COMMA 


\ 


CLEAR-SLASH 


] 


CLEAR-PERIOD 


«h . 


CLEAR-SEMICOLON 




CLEAR -ENTER 


T 


CLEAR-SHIFT-COMMA 


1 


CLEAR -SHIFT-SLASH 


} 


CLEAR-SHIFT-PERIOD 



You must have the book, "The C Programming Language" by Kemighan and 
Ritchie. Open it to page 15 and note the program shown at the top of the 
page. You are going to enter 1t. First, execute EDAS with: 

EDAS (LC) 

The "LC* 8 parameter tells EDAS to accept lower case input, set tab characters 
at every four positions, and use /CCC as the default file extension. You will 
observe the EDAS heading message. Now enter the command, "1". EDAS will go 
into Insert mode and display the first line number. As you enter each line, 
terminate it with <ENTER>. You should get into the habit of using the <TAB> 
key (right-arrow) to organize your LC code into neat indentations. It will be 
shown below as *<T>". Follow the line numbers shown below with the text as 
found In K & R. 

EDAS YOU TYPE 

00100 #1nclude stdio/csh <ENTER> ' 

00110 main() /* copy input to output */ <ENTER> 

00120 { <ENTER> ' . 

00130 <T> 1nt c; <ENTER> 

00140 <T> while (( c ■ getcharO) 1« EOF) <ENTER> 

00150 <TXT> putchar(c); <ENTER> 

00160 } <ENTER> 

00170 <BREAK> 

> w clone:d <ENTER> /* M ;d" specifies the drivespec */ 
New file! 

> b 



v 
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You have just entered an LC program, saved it under the name "CLONE/CCC:d", 
and returned to DOS Ready. Now enter the command (with u :d" representing your 
drivespec): 

00 LC (FILE-CLONE:d) 

If you have entered the program correctly 9 LC should compile your program and 
invoke its assembly to create the CLONE/CMD file. Try out your program 
according to K & R. 

If you want to start understanding the concepts of I/O redirection, turn 
to page 1-7 of the INTRODUCTION. The program you have just compiled into an 
executable CMD command is used to illustrate I/O redirection. Try Out the 
examples shown. 

»>» ««< 

»>» ATTENTION <«« 

>»» <«« 

If you are invoking LC with the DO LC (FILE-MYPROG) command and the 

EDAS assembly aborts with a Job Control Language, "Job aborted" message, you 

most likely mistyped one or more identifiers (variable names, function names, 

\ etc). You can easily discover the error by reinvoking the procedure with the 

command, 

DO LC (FILE-MYPROS.SHOW) 
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LC LIBRARIES 
STANDARD LIBRARY 



The standard library, LC/LIB, is a collection of useful functions that 
allows the user to interface with the world external to the program, without 
having to know the specifics of the particular environment that the program 
is running in. Thus, a program can be transported in source form to a 
different computer under a different operating system. Only the standard 
library need change between systems. 

The library is defined in a device independent way so that a program can 
use any device for input or output. Since any file is defined as a sequence 
of bytes, all devices can be interfaced to as files. LDOS already provides 
this type of device independence, thus the implementation of LC I/O 1s 
totally compatible with normal LDOS files. 

The standard library also provides functions to perform machine 
dependent operations, such as memory allocation and character set operations. 

Every program in executable form under LDOS requires a small run-time 
module in order to open standard I/O and provide I/O redirection, initialize 
the I/O and memory allocation functions, and to provide basic operations that 
LC programs require, such as MULTIPLY, OR, and AND. 

The library is constructed as a Partitioned Data Set. LC functions are 
stored in assembler source form as members of this data set. The standard 
library is accessed by the EDAS assembler from the "*SEARCH LC/LIB" command. 
v. Any member needed by your C language program is automatically linked with 
your program during the assembly phase of the LC compiled output. See the 
chapter titled, "OPERATOR'S GUIDE", for more information. 
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ALLOC () 



This function is used to allocate a memory block. Its syntax is; 



ptr > alloc ( nbytes ); 

nbytes - unsigned number of bytes needed. 

ptr - address of the block allocated. 



Ay 

AllocO is used to dynamically allocate memory during program execution. 
The complementary function, freeO, is used to release memory allocated 
through allocO. Alloc may be used to get table or buffer space when the 
amount of memory space available is unknown, such as a program designed to 
run In any size memory machine (16k, 32k, 48k). The programmer can call 
allocO with decreasing size of requested space until the space is allocated. 

RETURN CODE 



If a memory block has been allocated, the 
of the memory block. If insufficient memory 
allocation, allocO will return a null (81). 

WARNINSS 



value returned 
1s available 



is the address 
to satisfy the 



y 



The program must not access memory outside of the area allocated. File 
access routines use allocO and freeO to establish and release File Control 
Areas (FCA's). The programmer cannot assume that memory not allocated 1s free 
for use, since later file opens may cause memory overlays. It is advised that 
the programmer always use allocO and freeO, or sbrkO for all dynamic 
memory accessing. 



EXAMPLE 



symtbsz -■ symtbsz % symslz;/* make integral */ 
If ((syratab ■ alloc (symtbsz)) »» (8) 

abendCnot enough memory"); 
glbptr » startglb ■ symtab; 



Jy 



STANDARD LIBRARY 

4-2 



L C LIBRARIES 



\ 



DATA COMVERSIOMS: ATOK) ITOAO XTOK) ITOXO 



These functions are used to convert character strings of digits (decimal 
or hexadecimal) to their Integer value and vice versa. The syntax 1s as 
follows: 

■■■■■mSMU*SUinuasiMH»»BMU»MUU»»H»l>UtnM 

int ■ atoi( decs ); 

1to*( 1nt, decs ); 

Int ■ xtoK hexs ); 

1tox( lot, hexs ); 

Int - 1s an Integer value. 

decs - 1s a string containing decimal digits <0-9> 



hexs 



- 1s a string containing hexadecimal digits 
<0-9>, <A-F>, or <a-f>. 



v. 



These standard C functions are used to convert Integer values to their 
character string Image and the converse. Functions are provided to deal with 
character strings containing either decimal or hexadecimal digits. Left 
truncation of the integer value takes place 1f an excess number of digits 1s 
present (i.e. int-xtoi ("11000") would result in the Integer value of 4096 
decimal). Conversion of a decimal string will be modulo 65536. 



Note: 
reasons. 

RETURN CODE 



the C 1to1() function has not been implemented for obvious 



v 



There is no return code. 
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EXITO 



This function is used to exit your LC application and return to DOS. Its •>' 
syntax is: 



y 



I 

I ex1t( code ); 

! 

I code - integer return code. 

I 



Ex1t() allows the user to exit cleanly from a program and control the? 
consequences of exiting. Passing a zero (0) for the return <code> to ex1t() 
Indicates normal program termination, causing ex1t() to take the LDOS normal 
exit. If a non-zero <code> is passed, exit() will take the error entry into 
LOOS, thus aborting any JCL processing 1n effect. 

If the terminating program was invoked by the cmd() function, the value 
passed to exitO will be the value returned from cmd(). An exception is if a 
negative value value 1s passed to exitO, in which case a negative one (-1) 
1s returned to cmdO. 

ExitO closes all open files before returning to LDOS. 

RETURN CODE 

ExitO does not return to the caller. • 

WARNINGS 

For compatibility with other C language systems, the programmer should 
not depend on exitO to close the program's files (other than standard I/O 
files). 
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^ FCLOSEO 



This function is used to close an open file. Its syntax is: 



retcod » f close ( fp ); 

fp - the file pointer. 



FcloseO is used to close an open file and to free the file control area 
(FCA) for later use. The <fp> passed to fclose must have been obtained from 
fopenO. In LC, exitO also closes files; however, the programmer should use 
fcloseO to ensure compatiblity and portability. 

There is a limited number of files (determined by the MAXFILES compiler 
option), including standard files, that may be open at one time. FcloseO is 
used to free FCAs so an unlimited number of files may be accessed one after 
the other. 

RETURN CODE 



» The "retcod" will be non-zero 1f no error was detected in the closing 
V operation. If an error was detected, then "retcod" will be zero (0). 

WARNINGS 

The value passed to fcloseO must be a valid file pointer. If it is not, 
unpredictible things, such as destroyed disk files, reboots, etc., can 
result. 

EXAMPLE 



if (lastc !» 0xla) putout(0xla); 
fclose(fpl); fclose(fp2); 
printf("Files now closed"); 
exit(0); 
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FfiETSO 



This function is used to get a buffered line from a file. Its syntax is: 



I 



eofliid » fgets( buf, max 8 fp ); 

buf - address of the buffer area. 

m» - the maximum length of the Input string. 

fp - the file pointer. 



i 



FgetsO Is used to obtain a buffered line from a file. A file may be the 
console keyboard, the RS-232 Interface, or any input device or disk file. Up 
to (max) bytes will be placed in the buffer. Input 1s terminated when either 
an end of line (0DH) or end of file 1s encountered or maximum buffer size is 



reached. 



For compatibility with LDOS JCL files, keyboard line Input is performed 
using the §>KEYIN system call. FgetsO recognizes the BREAK key as the end of 
file from the keyboard. 

RETURN CODE 



..s 



\ 



The end-of-f1le indication, "eoflnd", 1s the return code, "eoflnd" Is 
NULL (zero) if an end of file is encountered; otherwise, "eoflnd" is <buf>. 



,js 



4-6 



L C LIBRARIES 



FOPENO 



This function is used to open a file/device. Its syntax is: 

fp ■ fopen( fspec, mode ); 

fspec - is the address of the file specification. 



mode 



- the address of the access mode identifier: 
"r" or "R" * read; "w" or "W" « write; 
"a" or "A" * append. 



y? 



V,. 



FopenO allows the programmer to initiate access to a file. Except for 
standard input, output and error files which are automatically opened, all 
files must be opened using fopen(). "fspec" points to a file specification 
string, "mode" points to a string defining the mode of access. Allowable 
modes are read, write or append. Only the first character of "mode" is 
checked, and that character may be upper or lower case. 



The file pointer 1s used whenever access to the opened file is 
If zero is returned, an error occurred during the open process. 

RETURN CODE 



needed. 



The file pointer, "fp' 
open operation, "fp" will 
during the open operation. 

WARNINGS 



, is returned if no errors are detected in the 
be set to NULL (zero) if an error is detected 



Opening the same file for both input and output with two or more calls 
to fopenO should NOT be done. If the file is accessed in th:s manner, it 
will create unpredictable results, possibly causing loss of file integrity. 

EXAMPLE 



getfile(fname) 

char *fname; 
{ FILE *fp; 

if C(fp»fopen(fname,"r")) ■■ NULL) 

{ printf("Open error - %-20s\n",fname); 
exitO; 

} 

else return fp; 
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FPRINTFO 



This function is used to create a formatted image for output to a 
device/file. Its syntax is: 



retcod ■ fpri«tf( fp, control, argl, arg2, ... ); 
fp - 1s a file pointer. 

control - 1s a string as specified under PRINTFO. 
argn - are arguments as specified under PRINTFO, 



RETURN CODE 



The "retcod" will be zero if no error was detected 1n the output 
operation. If an error was detected, then "retcod" will be EOF (-1). 



v>- 
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FPUTSO 



This function will output a string to a file/device. Its syntax is: 



retcod ■ fputs( string, fp ); 

string - is the address of the string to be output. 



ft 



FputsO outputs to the file defined by "fp", all characters pointed to 
by "string", up to the first zero byte. 

RETURN CODE 



The "retcod" will be zero if no error was detected in the output 
operation. If an error was detected, then "retcod" will be equal to "EOF" 
(-1). 

WARNINGS 



- \ 



V. 



Calling fputsO with an invalid file pointer can result in destruction 
of files or other havoc. 
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FREEO 

This function frees memory allocated with allocO. Its syntax is: 



I I 

I free( ptr )s I 



ptr - address of the bottom of the memory block. | 

FreeO is called when a memory block allocated to the program by the 
function allocO Is no longer needed, and the programmer wishes to free the 7 



memory space for later use. "ptr" points to the first (lowest) byte allocated 
to the program by allocO. 

RETURN CODE 

There is no return code. 
WARNINGS 

Calling freeO with an address other than that obtained from a call to 
allocO will cause unpredictable results, probably a program crash when the 
next allocO occurs. 



^, 
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GETCO 



This function is used to fetch (input) a character from a f1le/dev1ce. 
Its syntax is: 



I c - getc( fp ); 

I fp - 1s the file pointer. 
I 



GetcO 1s used to input a single byte from a file, "fp" must be obtained 
from fopenO or be a standard file pointer. Any of the 256 possible binary 
codes may be input using getcO. An end of file code, "EOF" (-1), 1s returned 
if end of file 1s encountered. 

RETURN CODE 



The return code is the integer value of the character input from the 
file. If an end of file is encountered, then "EOF" (-1) 1s returned. 

WARNINGS 



The "fp" must be a valid file pointer or devastation may result. You are 
warned ! 

If "c" is to be stored before testing for end of file 1t must be stored 
in an integer variable. If not, the end of file value will be truncated and 
will remain undetected. 

EXAMPLE 

filecopy(fp) /* copy a file to the standard output */ 

FILE *fp; 

{ 

int c; 

while ((c « getc(fp)) 1» EOF) 
if (c !* putc(c.stdout)) 

abort( "Output file write error"); 
> 
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GETCHARC ) -^ 

■ssaasaiia 

/ 

This function is used to get a character from standard input. Its syntax J 
is: 



I c m getcharO; 

I - there are no parameters. 



GetcharO Inputs a single byte from the standard input. GetcO is u§^d 
to perform the input. 

RETURN CODE 



The return code is the integer value of the character input from the 
file. If an end of file is encountered, then "EOF" (-1) is returned. 

WARNINGS 

If <c> is to he stored before testing for end of file, it must be stored 
In an integer variable, or the EOF value will be truncated to 255. 

EXAWLE 

bytes * lines • 9; 

while( (c^getcharO) !• eof) 
{ putchar(c); 

•H-bytes; 

if (c ®« eol) -M-lines; 
> 
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GETSO 



This function fetches (inputs) a buffered line from standard input. Its 
syntax is: 



I I 

I eoflnd ■ gets( buffer ); I 

I I 

I buffer - is a pointer to an 81 byte buffer. | 

I I 



GetsO Inputs a line up to 80 characters long from the standard input 
and places the line in memory starting at the address given by <buffer>. 
FgetsO is used to perform the input. 

RETURN CODE 



The end-of-file indication, "eofind", is the return code, "eofind" is 
NULL (0) if an end of file is encountered; otherwise, "eofind" is <buffer>. 



WARNINGS 



The "buffer" must be at least 81 characters long. 
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MOVEO 



This function will copy a memory block in memory. Its syntax is: 

nsisausassstUHStasssississssssissssKssssisxsisiisassasaaix 



H6W@( 

pfrm 
pto 

len 



, pto, len ); 
- the address of the block to be moved. 



- the address of the block's new starting 
address. 

- the length of the block, 1n bytes. 



*i 



This function will perform a nondestructive move of a memory block. That 
means that if the "pto" address is less than the "pfrom" address, the move 
will start from the beginning of the block. If the M pto M address is greater 
than the "pfrom M address, the move will start from the end of the block. 

RETURN CODE 



There is no return code. 

WARNINGS 



There is no checking on the magnitude of "Ten"; thus, a moveO with an 
erroneous value for "len" could overwrite a critical portion of memory. 



,/ 
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ISALPHAO ISDieiTO ISLOWERO ISUPPERO 



These functions are used to test a character. Their syntax is: 



retcod 
retcod 
retcod 
retcod 
char 



isalpha( char ); 
1sd1g1t( char ); 
islower( char ); 
i supper ( char )j 
- is the character under test. 



"isalpha" is used to determine if a "character" is an upper-case or 
lower-case alphabetic (<A-Z, a-z>). "isdigitO" is used to determine if a 
"character" is a digit in the range <0-9>. "islowerO" is used to determine 
if a "character" is an alphabetic in the range <a-z>. "isupperO" is used to 
determine 1f a "character" is an alphabetic in the range <A-Z>. 

RETURN CODE 



Each function will return a TRUE (1) or FALSE (0) value based on the 
results of the test. 



EXAMPLE 



if ( isdigit(char)) 

printf( "Character is <0-9>\n M ); 
else if ( islower(char)) 

printf( "Character is <a-z>\n"); 
else if ( isupper(char)) 

printf( "Character 1s <A-Z>\n M ); 
else 

printf( "Character is none of the above\n")j 
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PRINTFO 



is: 



This function creates a formatted image for standard output. Its syntax 



BBsaasasssasBsssssassssassassasssssssssssssasssssasassssssssasa 

printf( control, argl, arg2, ...); 

control - is a string containing transparent printing 
characters and conversion specifications. 



argn - are arguments to be formatted for the output 
print image. 

s^s3atatssssssas3sss3assas3ats3S33C3sassssaasasa!3t33S33ssaiat3i3ta!aiS3338ss3a>3sai3i 



1 



This function is used to create an output image to the standard output 
device. The specifications for formatting the output are determined by the 
character string, "control". This string will contain ordinary characters 
copied directly to the output image and/or specifications denoting the field 
conversions of all arguments. The conversion specifications take the form of: 

X{-HxxxH.yyy}char 

As can be noted, the specification is a sequence of sub-fields of which the 
percent sign {%) and the "char" are mandatory. The percent is an "escape" 
character signaling the start of the field specification. The "char" denotes 
the format of the output field image {binary, decimal, string, etc.}. The 
sub-field specifications are interpreted as follows: 

% « the mandatory specification initiator, 

■ specifies that the value will be left-justified within 
the print field image, 

xxx ■ specifies the minimum width of the print field image, 

•yyy ■ specifies the maximum number of string bytes to print, 

char » the conversion character {b»binary, o»octal, d»decimal, 
x^hexadecimal, s*string, c^character, u«unsigned}. 

Any portion of the control string which cannot be interpreted as a 
conversion specification field is considered to be transparent printing 
characters and will be passed directly to the print image. 

EXAff>LE 



printfCXd characters, %d lines were copied\n", bytes, lines); 



,> 
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PUTCO 



this function is used to output a character to a file. Its syntax is: 

xisssaiaxsssiisaaiaisisixsissiasiHsssiinaisssiaafaaaaiMaaaBX 

cret ■ pytc( c, fp ); 

c -is the character to be output. 

fp - is the file pointer for the output file. 



PutcO is used to output single characters to a file, "c" is any of the 

256 possible character codes. If an integer value is passed it is 

left-truncated, so that only the least significant byte is output. 

RETURN CODE 



The return code, "cret", is the character passed in "c" if no errors are 
detected otherwise, it will be different from the character passed in "c". 

WARNINGS 

"fp" must be a valid file pointer obtained from fopenO or one of the 
standard I/O pointers (stdin, stdout, stderr) or destruction of files may 
occur. 

EXAMPLE 



if ( putc( c, fp ) 1» c ) 

return(l); 
else return (0); 



U 
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PUTCHARC) 



This function is used to write a character to standard output, 
syntax is: 



Its 



asiiassasKSsassasaiscsaaasssassissssasaBasBsaxzxsucussxauasz 



eret « pytchir( c ); 

c - is the character to be output. 



PutcharO outputs the character "c" to the standard output file, 
is used to perform the output operation. 

RETURN CODE 



PutcH 



The return code, "cret" is the character passed in "c", if no errors are 
detected. 

WARNINGS 



There are no warnings. 



-.^ 
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PUTSO 



This function is used to output a string to the standard output. Its 
syntax is: 



retcod » puts( string ); 

string - is the address of the string to be output. 



PutsO outputs <string> to the standard output file. All characters up 
to the first zero byte are output. If an error occurs during output, the 
value "EOF" (-1) is returned; otherwise, a zero Is returned. 

RETURN CODE 



The "retcod" will be zero if no error was detected in the I/O operation, 
If an error was detected, then "retcod" will be set to "EOF" (-1). 

WARNINGS 



There are no warnings. 

EXAMPLE 



if (argc!*3) 

{ puts("Format error: compare filel file2\n"); 

exitO; 
} 
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SBRKO 

This function is used to allocate a memory block. Its syntax is: J 



ptr • sbrk( nbytes ); 

nbytes - an unsigned integer number of bytes needed. 



SbrkO reserves memory for use by a program from the system memory pool. 
The memory allocated by sbrkO cannot be deallocated until the program 
finishes execution. AllocO uses sbrkO to request blocks of memory as 
needed. If the memory requested will only be needed for part of the execution 
of the program, it is recommended that allocO be used. 

RETURN CODE 

The return code* "ptr", is the address of the allocated block of memory 
if the sbrkO was successful. If not enough memory is available to satisfy 
the request, "ptr" is set to NULL (0). 

WARNINGS N 

/ 
Only memory allocated by sbrkO or allocO should be used by the 

programmer for dynamic space. File opens and closes, including standard 

files, use these functions for setting up File Control Areas (FCA's). These 

FCAs can be clobbered if the program accesses unauthorized memory. 



M 



STANDARD LIBRARY 

' 4-2® 



J 



L C LIBRARIES 



TOLQWERO TOUPPERO 

These functions are used to convert a character from one case to the 
opposite case. Their syntax 1s: 



A 



c ■ tolower( char ); 
c * toupper( char ); 

char - 1s the character under test. 
c - Is the converted result. 



■uiiu>iamwan»ua»aa»»M»a»ittM»u»M»»»iiuu 

"tolower" Is used to convert an upper-case character <'A' through *Z'> 
to a lower-case alphabetic <'a' through % z % >). "toupper" performs the 
opposite function; a lower case character is converted to upper case. Both 
functions affect only alphabetic characters; numbers, special symbols, etc., 
are returned unaltered. 

RETURN CODE 



Each function will return the converted character, as required. 



sxanimrq* \iimmm 
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INSTALLATION LIBRARY 



The installation library is a collection of functions very specific to 
the particular machine LC is running on. Also included are functions not 
considered to be "standard" C functions These functions group themselves into 
STRING functions, PLOTTING functions, and CONTROL functions. All of the 
functions are contained in the library, IN/LIB (note: STRCAT, STRCMP, STRCPY, 
and STRLEN are documented under the string functions; however, since they are 
standard C, they are physically located in the LC/LIB library). 

If your LC program is going to make use of any of the functions 
contained in the IN/LIB library, you will have to insert the compiler 
directive statement: ^ 

#opt1on IN/LIB 

in your C source program. 



v^ 
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PRIMITIVE PLOTTING FUNCTIONS 



The plotting functions support the block graphics mode available to the 
CRT screen. The installation library plotting functions include functions to 
control individual pixels (picture elements), as well as to create various 
line constructions. The primitive functions are used to turn on, turn off, or 
determine the status of any point (pixel) in the screeer issageu The syntax of 
these functions is: 



iiiiiuiiiiiiiaiuiii 



\ 



retcod ■ pixel ( funcod, x, y ); 

retcod * po1nt( x, y ); 

reset ( x, y ); 

set( x, y ); 

funcod - specifies whether the pixel is reset (0), 
set (1), or pointed (2). 



x 



• specifies the horizontal coordinate. 
. specifies the vertical coordinate. 



/•f 



The "pointO" function will return the status of the pixel at the 
coordinate, x.y. A return code of one (1) indicates that the pixel is turned 
on (light) while a zero (0) indicates that the pixel is turned off (dark). If 
the pixel contains something other than a graphic character, a negative two 
(-2) is returned. A negative one (-1) indicates the point x,y 1s out of 
range. 

The "resetO" function will turn off the specified pixel while the 
"setO" function turns on the pixel. Neither of these two functions provides 
a return code unless x or y is out of range. 



"pixel ()" function can be used to point, reset, or set the pixel 
on the function code supplied as the argument, "pixel O" issues a 



is Indicative of "point" (2) 



The 
depending 

return code only when the function code passed 
or when an argument is invalid. 

The plotting functions specified above refer to the arguments detailed 
as follows: 

funcod 



This function code specifies the operation to be performed on the pixel. 
It can be an integer value in the range <0-2>. If the argument passed 1s 
outside of this range, the return code will be negative three (-3) indicating 
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an invalid function code. These codes are used as follows: 

- Indicates the "reset" function which will turn off (make dark) 

the pixel. f 

1 - Indicates the "set" function which will turn on (make light) the 
pixel. 

2 - Indicates the "point" function which will return the status of 
the specified pixel. The status will be zero (0) for reset, one (1) 
for set, negative one (-1) if xl.yl is not in the CRT image, or 
negative two (-2) if the specified pixel does not contain a graphic 
character. 

x or y ^ 

This integer value specifies the pixel position along the x-axis 
(horizontal) or y-axis (vertical). The value is a virtual pixel, which means 
that it does not have to be a position in the CRT image. However, where a 
line is being constructed, only that part of the line actually in the CRT 
image area will be plotted. The direction away from the origin is always 
considered to be in the positive direction (for more information on this 
subject, see the pmodeO function).- 

RETURN CODE 

Return codes are provided by the above functions where applicable. These f 
codes are indicative of the following: • 

- Indicates that the pixel is reset Cpoint(x.y) or 

pixel(2,x s y)3. 

1 - Indicates that the pixel is set Cpoint(x.y) or 

pixel(2,x,y)]. 

-1 - Indicates that the point xl,yl is out of range (i.e. 
virtual and does not appear in the CRT image). 

-2 - Indicates that the pixel does not contain a graphic 
character Cpoint(x.y) or pixel(2,x,y)]. 

-3 - Indicates that the function code passed to pixel () 
1s Invalid (not In the range <0-2>). 

EXAMPLE 



This routine plots a horizontal line: 

for (x » 0, y » 40; x < 128; x++) 
set( x, y ); 



,r 
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ADVANCED PLOTTING FUNCTIONS 



These functions are used to plot geometric shapes 
and circles}. Their syntax is as follows: 



{lines, rectangles, 



retcod - box( funcod, xl, yl, x2, yZ ); 

retcod - c1rde( funcod, xl, yl, rl ); 

retcod ■ 11ne( funcod, xl, yl, x2» y2 ); 

funcod - an operation code to set (1) or reset (0) the 
pixels involved in the geometric plot. 

xl.yl - the coordinate of the first point defining 
the geometric shape. 

x2,y2 - the coordinate of the second point defining 
the geometric shape. 

rl * the radius of the circle in "y" units. 



**? 



v.- 



The "lineO" function will plot a line connecting coordinate 
with coordinate point x2,y2. 



point xl,yl 



The "circlet )" function will plot a circle at coordinate center point 
xl,yl of radius rl. The integer value, "rl", specifies the radius of the 
circle. Since block graphics are generally taller than their width, it is 
necessary to specify the radius in units of either "x" or "y". Within these 
plotting functions, "rl" is a value representing the radius in 



"y" units. 



The "boxO" function will plot a rectangle around the diagonal specified 
by the coordinate point pairs, xl,yl and x2,y2. If the coordinates specified 
either equal x (xl » x2) or equal y (yl » y2), then the rectangle will 
diminish to a line. The rectangle will collapse to a point, if both xl*x2 and 
yl»y2. 

VIRTUAL POINTS 



The concept of virtual points is an important one. What it means is that 
your plotting routines do NOT have to limit themselves to the CRT image area. 
For example, a circled, 0,0, 20); function describes a circle about the 
origin. This means that a portion of the circle would be plotted off of the 
CRT image. The plotting functions permit your arguments to describe such 
"virtual" images; however, any portion of the geometric shape that would be 
outside of the CRT image area is inhibited. Thus, in the above example, only 
a portion of a circle (an arc) will be plotted. 
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It is also important to note that if any virtual pixel is described in 
your arguments, the function will return a negative one (-1) after completing 
the entire geometric plot. Your program can make use of this return code if 
it needs to detect this fact. 

RETURN CODES 

Return codes are provided by the above functions where applicable. These 
codes are Indicative of the following: 

-1 - Indicates that the coordinate points xl,yl , x2,y2, 

or a portion of any plot is out of range (i.e. virtual 
and does not appear in the CRT image). 

-3 - Will be returned if the function code passed is invalid '*» 

(not in the range <0-l>. 

EXAMPLE 

The following routine will plot increasing rectangles starting at the. 
center of the CRT image: 

for (xl»63,yl»23,x2=64,y2»24; xl >» 0; xl~,yl~,x2++,y2-H-) 
boxd, xl, yl, x2, y2 ); 

Try out the next example program: 

loption inllb 

main() 

{ 

int xl,x2,yl,y2,t,tl; 

for ( xl*0, yl=0, x2=127, t ■ ; t <» 47 ; t++ ) 
{ lined, xl,yl,x2,t); 
line(0,xl,yl,x2,t); 
} 
for ( y2»47,t » 127 ; t >» ; t— ) 
{ lined, xl,yl,t,y2); 
I1ne(0,xl,yl,t,y2); 
> 
exit(0); 
} 
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PLOTTING CONTROL FUNCTIONS 



Two functions are provided that interface with and control certain 
aspects of the pixel plotting functions. The "pmodeO" function establishes 
the CRT image area as one of the four quadrants in the cartesian coordinate 
system. Another function, "plocO", establishes the starting address of the 
CRT image area. The syntax of these functions is: 



ploc( address ); 

retcod » patode( quadrant ); 



address 



quadrant - 



specifies the starting address of the 
plotting Image area. Plotting functions use 
the CRT address unless changed by pmodeO. 

sets the plotting image to quadrant <l-4> of 
the x-y plane {initialized to quadrant 4}. 
If quadrant . ■ J3, then the current quadrant 
number in effect will be returned. 



/*"£ 



""N The pmodeO function is quite useful when your application concerns the 
graphing of mathematical functions in the standard cartesian coordinate 
system. Since most functions are graphed 1n the first quadrant, a "pmoded)'* 
will establish the image area for that purpose. Please note that any 
characters/graphics currently on the screen at the time the pmodeO is given 
are left undisturbed - pmodeO does NOT refresh the current screen contents 
to the revised quadrant but prepares the plotting functions for the new 
quadrant. 

"Quadrant" is used when changing the base origin of the plot image area 
with the pmodeO function. The image area is considered to represent only one 



quadrant of the x-y plane in the 
are numbered as follows: 



cartesian coordinate system. The quadrants 



0|0 
*0|0~ 

I 



with the point 0,0 (the origin) appearing at the corner identified with the 
letter "0". The standard quadrant used by the plotting functions will be 
quadrant 4 unless changed with a pmodeO function call. Remember that the 
direction away from the origin is always considered to be positive. 

The plocO function can be very powerful in creating dynamic displays. 
By establishing an off-CRT buffer equal in length to the CRT image area, its 
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address can be passed via plocO so that the plotting functions plot into the — . 

buffer. The buffer could be subsequently moved to the CRT image area with the 

moveO function. \ 

RETURN CODES 

Return codes are provided by the pmodeO function where applicable. 
These codes are indicative of the following: 

1-4 - Indicates the current quadrant in effect when a 
pmodeO); function is invoked. 

-1 - Returned if "quadrant" is not in the range <0-4>. 
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S«8 S 9E S£ 39i 33S 5B83I S3S3E3 

The most important bit of information to convey at this point concerning 
the use of strings and \he C language, is that the language provides no 
internal mechanics for dynamic string maintenance. Strings are generally 
stored in character arrays - arrays are fixed in length at the time of their 
declaration. Therefore, when you employ the string functions contained in 
this installation library, remember that your application must provide the 
proper array sizes to deal with the expected lengths of the strings. Where 
string lengths are indeterminate at the time the application is coded but are 
determined rather at run time, it may be prudent to consider testing the 
length of a string operation result prior to actually performing the ^tended 
operation to ensure that the operation will not exceed the array size of the 
array receiving the string result. 

Another point worth remembering is that there is no upper limit on the 
length of a string in the C language. A string is stored contiguously in 
memory. The last character of the string is denoted by a null byte (hex zero) 
at the end. Thus, any array used to store a string should be defined with a 
size one byte greater in length than the maximum length of the string it is 
to contain. This will allow for the storage of the terminating zero byte. For 
instance, the string "Hello", is stored as (shown in hex): 

48 65 6C 6C 6F (90 

N The string functions provided in the installation library correlate with 
the string functions provided in various Implementations of Microsoft BASIC. 
Again, remember that no dynamic string allocation/compression takes place 1n 
these routines. 

The string functions, strcatO, strcmpO, strcpyO, and strlenO are 
documented in this section. However, since these functions are considered to 
be "standard C" functions, the routines are supplied in the standard library, 
LC/LIB. 
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The functions provided take the following format: 

aS3S13SS3SS8S&3a31338i8SS3S83I3SSS33S3S3S3S83XSISSSS3Sa 

strcat( dest, source ); 

reteod » $trcmf»( strlnqJL, string_2 ); 

strcpyt dest, source ); 

retcod * strep! ( source, dest, pos, count ); 

strept( dest, source, repeat ); 

retcod » strf1nd( dest, source, pos ); 

str1ght( dest, source, count ); 

strleft( dest, source, count ); 

retcod ■ strlen( source ); 

retcod » strnid( dest, source, pos, count); 

count - is the integer sub-string length. 

dest - is a pointer to the destination string. 

pos - starting index position or array subscript. 

source - is a pointer to the source string. 

repeat - a repetition counter. 

B<iBSsaat<S3sss3aas»assssss*ssiisassx3<ssii*ai3SStss,s«iisa3sasis 

STRCATO 

The strcatO function will concatenate (append) the source string to 
the destination string. 

STRCMPO 



J 



J 



The function, strcmpO, will compare str1ng_l to string__2. If the 
stringj. would appear above string_2 in an ascending sorted list, "the return 
code will be negative. (<0). If the two strings are equal, a zero (0) will be 
returned. A return code of a positive value greater than zero (>0) indicates 
stHngl to be below string 2 in an ordered list. If you are unfamiliar with 
how ASCII strings are u ora r ered M , perhaps a strong example will clarify this 
discussion. The following is an ordered list of strings in ascending order: 
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a8bcde 

abc 

abed 

jira 

karl 

rich 

roy 

th i s_i s_aj on g_s tr i n g 

Keep this ordered 11st in mind in the following examples. The statement: 

if (strcmp("abcVa8bcd"> < 0) ? pr1ntf( "above") : prlntf ("below"); 

should print the word, "below" since the string, "abc" is below the 7 string 
"a8bcd" in an ascendingly sorted list. The statement: 

if (strcmp( "abc", "abed") < 0) ? printf( "above") : prlntf ("below"); 

should print the word, "above" since the string, "abc" is above the string 
"abed" in an ascendingly sorted list. 

STRCPYO 



The strcpyO function copies an image of the source string to the 
destination string buffer. 

STREPLO 



The function, strepK), replaces that portion of the destination string 
starting at relative position "pos" and continuing for "count" characters 



[the destination substring] with the source string. The arguments "pos' 
"count" control where and how much of the destination string is to be 
replaced (i.e. what is the substring). The length of the replacement string 
is the length of «the source string. If "count" is zero (0), then an insert 
operation is performed without deleting any characters of the destination 
string. If the source string is null (i.e. of zero length), then only the 
identified sub-string is deleted. If "dest+pos" exceeds the bounds of the 
destination string, an out-of-range error will be returned and the string 
operation will be aborted. Bear in mind that this function behaves 
differently than the Microsoft BASIC MID$» function; however, the LC strepK) 
function performs as a string replacement algorithm should perform. 

STREPT( ) 



The streptO function replicates the source string into the destination 
string the number of times indicated by "count". Note that the replication 
uses the entire source string and not just the first character. Thus a 
statement such as: 

strept(newstring,*'*.",10); 
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will create newstring equal to "*. *.*.*. *.*.*. *.*.*.". 
STRFINOO 

The function, strfindO, will search the destination string for the 
first appearance of the source string. The destination string will be 
searched starting at the position "dest+pos". If the source string is a null 
string, the value of "pos" will be returned. If the destination string is a 
null string, a negative one (-1) will be returned. If the source string is 
found in the destination string, its position relative to the beginning of 
the source string will be returned. If the source string is not found (i.e. 
is not a sub-string of the destination), a negative one (-1) will be 
returned. 



STRIGHTO 



jf-y 



The strightO function will copy the rightmost "count" characters of the 
source string (the sub-string) to the destination string. This is NOT an 
append operation. The destination string 1s replaced with the sub-string. If 
"count" is zero, the destination becomes a null string. If the "count" is 
greater than the source string length, the entire source string is copied. 

STRLEFTO ... 

The function, strleftO, will replace the destination string with the 
leftmost "count" characters of the source string. If count Is zero, the 
destination becomes a null string. If the "count" 1s greater than the source 
string length, the entire source string 1s copied. 

STRLENO 

The strlenO function returns the length of the source string. 
STRMID( ) 

mt «*> m «*» *a» on o» an 

The function, strmidO, will replace the destination string with the 
substring of "count" characters starting at position "source+pos" of the 
source string. If "count" is zero, the destination string will be null. Also, 
if "source+pos" exceeds the bounds of the source string, an out-of-range 
error (-1) will be returned and no string replacement will occur. "Count" may 
be greater than the length of "source" plus "pos". 



-~S 
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STRING FUNCTION ARGUMENTS 



The string functions specified above reference various arguments 
detailed as follows: 

DEST 

This represents a pointer to a character array. The argument that 1s 
passed to a function 1s an address when the argument references an array; 
therefore, a pointer is Identified to the string functions by the >/ery nature 
of the character array declaration as in: 

char sC81] 

which establishes a character array capable of holding up to an 80-character 
string. 

SOURCE 



This also represents a pointer to a string which 1s used as the "source" 
string where the function requires more than one string in its arguments. 

POS 

This represents a starting position relative to the beginning of a 
string. It is essentially used as an index or subscript into the character 
array ( <» POS < n ). 

COUNT 

This parameter is used, where required, to indicate the length of some 
substring. In the case of streptO, it is used to specify the replication 
quantity. 

RETURN CODES 



The return code of strcmpO is <0, 0, or >0 as noted above. The return 
code of strlenO is the length of the target string. The functions strmldO 
and strepK) will return a negative one (-1) if the arguments specify a 
resulting position outside the range of the string. For instance: 

if ( strmid(s,"error",6,3) ■» -1 ) printf("String error!"); 

will result in the error message display since the position, 6, is not in the 
range of the string, "error". The remaining string functions do not have 
return codes. 
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CONTROL FUNCTIONS 



The remaining functions included in the installation library not 
previously detailed perform miscellaneous tasks. The syntax of these 
functions is as follows; 

S8»aiS*SSaXISBS33ZS31SS33SaSSa3SS3<3SSS>SSS>SSlSaSX3SSJI3SSI 



I 

I f1ll( buffer, count, char ); 
retcod * freemanO; 
retcod * inkeyO; 
reteod ■ 1nport( port ); 
outport( port, value )j 
retcod « curposO; 
cursor( row, col ); 
date( s ); 
t1me( s )-; 

e»d1( "ccwwasid string 8 ); 
retcod«and( "command string" ); 



zap a memory block 
fetch memory size 
scan the keyboard 
input from a port 
output to a port 
fetch cursor position 
reposition the cursor 
fetch the system date 
fetch the system tifne 
exit & command DOS 
command DOS & return 



retcod«cal1( address, regs ); - generalized call 



^ 



FILLO 



The function, fillO, will propagate the character, "char", into the 
memory "buffer" for "count" bytes. If "char" is passed as an Integer value, 
the low-order byte is used for the propagation. Note the* difference between 
streptO and filK). 

INKEY() 

The inkeyO function makes a single scan of the keyboard and returns the 
ASCII value of any depressed key. It will return a zero if no key is pressed. 

INPORT 



x 



The function, inportO, returns as an integer, the value read from the 
specified port. 
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OUTPORTO 

The outportO function outputs the integer value to the port. The value 
is truncated to its low-order byte. 

CURPOSO 



The current location of the cursor can be recovered with the curposO 
function. It returns the cursor position as an encoded value. The cursor row 
1s in the high-order byte while the cursor column occupies the low-opder byte 
of the Integer return code. 

CURSOR () 



To reposition the cursor, use the cursorO function. The cursor is 
re-positioned to the location identified by the arguments. If the position 
that would result is not on the CRT screen, a range error (-1) 1s returned, 
"x" must be 1n the range, <0-63>, while M y" must be in the range, <0-15>. 

DATEO 

The dateO function will place the system date into the string "s". The 
format is MM/DD/YY. The string should be defined as a character array of 
minimum dimension 9. 

TIMEO 

The timeO function will place the system time into the string "s". The 
format is HH:J#1:SS. The string should be defined as a character array of 
minimum dimension 9. 

CMDIO 



The function, cmdiO, will invoke an exit from the running LC program 
and schedule the DOS execution of the command contained in string "command 
string". This could be used, for instance, to chain to another C program. The 
crndK) argument can be either a string defined in the function call or a 
pointer to a character array which contains the command string. 

CMDO 



If you want to execute a command and return to your. LC program, use the 
cmd() function. This function will pass the command stored in string "command 
string" (or the string pointed to by a pointer argument) to the DOS command 
interpreter. Upon completion of the command, control will be returned to the 
running LC program. Your program and variables will be saved during the 
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execution of the command. If the executing command returns through @EXIT, a 
return code of zero (0) will be retrieved. If the ©ABORT exit is taken, the 
return code generated will be obtained from the value contained in register 
pair "HL". If this value is positive (i.e. bit 15 reset), it becomes the 
return code. If the value is negative (i.e. bit 15 set), then a negative one 
(-1) will be returned. 

CALLO 

A generalized assembly language interface routine, callO, is available 
in the installation library. "Regs" is an integer array of dimension 6 which 
should contain the quantities you want placed into the register pairs {AF, 
BC, DE, HL, IX, and IY for regs[0]-regsC5] respectively} prior to calling the 
routine at location "address". The "regs" array will be stuffed with th§ 
register contents that existed upon return from the called routine. The 
return code will be zero (0) if the Z-flag is set upon return from the called 
routine; otherwise, the return code is one (1). For more information on the 
use of callO, see the chapter on ADVANCED TOPICS. 

FREEMIiMO 

'mmamnanmim<m<m<m 

FreememO returns the maximum amount of memory which can be obtained 
from allocO or sbrkO. 



* < K^J' 
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LC does not have floating point arithmetic built into the compiler. 
Thus, floating point expressions are not allowed in the normal manner. 
However, this floating point function library allows the programmer to use 
the floating point routines built into the TRS-80 BASIC ROM. These functions 
provide access to single and double precision math, all the trigonometric 
functions, random number generation, and conversion to and from ASCII 
strings. 

Before any floating point math can be done, the function "fp1n1t() B must 
be called. FpinitO initializes some data areas used by the TRS^0 ROM 
floating point routines and sets up linkages for error recovery. The calling 
of fplnltO and the automatic search of the floating point library 1s 
accomplished when you add the compiler declaration: 

loptlon FPLIB 

to your C-language source program. This establishes the protocol necessary to 
invoke an automatic search of the floating point library in the LC/ASM file 
via the »*SEARCH FP/LIB" statement. The floating point initialization 
function, fpinitO, is normally called automatically by LC's initialization 
routines if "#option FPLIB" has been specified. However, if the user changes 
or substitutes different Initialization code, the user's program must call 
fpinitO. 

Numbers may be stored in two different formats: single or double 
precision. Throughout the library routines two consistent abbreviations are 
used: "f" for floating point SINGLE precision, and "d" for floating point 
DOUBLE Precision. Functions beginning with or containing either of these 
abbreviations operate on the precision indicated. Single precision nuntoers 
are stored in four bytes; double precision numbers in eight bytes. The 
programmer may declare either an integer array, or a character array to 
allocate space for variables in their program. Both of the statements, 

char fpnum[43; 
int fpnumr.2]; 

declare a 4-byte single precision field. Both of the statements, 

char dpnum[8]; 
int dpnumC43; 

declare an 8-byte double precision field. 

Take care in how you pass the parameters required by each function: THE 
ADDRESS OF THE FIELDS ARE PASSED. Thus, if the declarations, "char 
fpnum[4],dpnumC8];", are used when calling a floating point library routine, 
the address of the first character (represented by the array name) should be 
passed. For example: 

atof("3.1416",fpnum); 

4 
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atod( "3.1415926 \dpnura) ; 

converts the strings containing PI to single and double precision and places 
the results into memory at locations fpnum and dpnum, respectively. 

If you are writing an assembly language routine that will interface to 
the FP /LIB. routines, the assembler statement: 

I FPLIB DEFL -1 

should appear in your code. This statement forces a search of FP/LIB in the 
LC/ASM file. 

ye wish to acknowledge our indebtedness to Insiders Software 
Consultants, Inc. for their book, THE B00K - ACCESSING THE TRS-80 ROM. Volume 
1, which provides vital information on interfacing to the ROM math routines. 
Although the functions in FPLIB do not require any knowledge of how the BASIC 
ROM In the TRS-80 functions, it can be helpful to have "THE B00K" for a 
reference to explain the details of floating point operation. 



r 
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FPIMIT 



This function is used to initialize interfacing to the ROM math routines 
and force a search of the floating point library during the assembly of 
LC/ASM. Its syntax is: 

naiiixsuzusutii»u*»ttix33ii»xiuusiiaaa»3ia»iiua»i 
f 

I fplnltO; 

I - there are no arguments. 



This function 1s normally called automatically by an LC program which 
has any module specifying "#opt1on FPLIB". In cases where normal 
initialization has been bypassed, a direct call to fpinitO by the user 
program will be necessary since fpinitO MUST BE CALLED before using any of 
the floating point functions in the library. It sets up certain data areas 
used by the floating point ROM routines, and provides error recovery linkage. 
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SINGLE PRECISION OPERATIONS 

3SS8 Sf S3 SS M 39 SB SB 13 3BSBS S3 M M SS MM 28 83S3 Si 



The following functions can be used to operate on single precision 
fields (length 4). Their syntax is as follows: 



1 reteod ■ 


fadd( vl, 


v2 


); 


- 


vl » 


vl + v2 


1 retcod «■ 


fsub( vl, 


v2 


); 


- 


vl ■ 


vl - v2 


1 retcod ■ 


fnul( vl, 


v2 


); 


. 


vl « 


vl * v2 


1 retcod * 


fdiv( vl, 


v2 


); 


<r» 


vl a 


vl / v2 


1 retcod ■ 


fsb$( vl, 


v2 


); 


«* 


vl ■ 


abs(v2) 


1 retcod ■ 


fatn( vl, 


v2 


); 


m 


vl » 


arctan(v2) 


1 retcod * 


fcnp( vi s 


v2 


); 


<B» 


compare vl to v2 


I retcod ■ 


fcos( vl, 


v2 


); 


*» 


vl ■ 


cos(v2) 


1 retcod ■ 


fexp( vl. 


v2 


); 


- 


vl ■ 


exp(v2) 


1 retcod ■ 


ff1x( vl, 


v2 


); 


tm 


vl * 


fix(v2) 


1 retcod ■ 


f1nt( vl, 


v2 


); 


- 


vl ■ 


1nt(v2) 


1 retcod • 


flog( vl, 


v2 


); 


- 


vl - 


log(v2) 


1 retcod ■ 


fra1se( vl, v2 )j 


- 


vl ■ 


vl ** v2 


1 retcod s 


fmd( vl, 


v2 


)s 


- 


vl ■ 


rnd(v2) 


1 retcod ■ 


fsgn( vl 


)? 




«» 


retcod • 


sgn(vl) 


1 retcod » 


fs1n( vl, 


v2 


); 


03k 


vl * 


s1n(v2) 


1 retcod ■ 


fsqr( vl, 


v2 


); 


«B 


vl « 


sqr(v2) 


1 retcod » 


ftan( vl, 


v2 


); 


. 


vl * 


tan(v2) 


1 vl & v2 


- are the address of 


singl 


e precision fields. 



<*•? 
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•^ These functions perform calculations on two single precision fields and 

place the result in the first field specified in the argument list (vl). In 
the event of an error, vl 1s unchanged and can be examined to determine the 
cause of the error. Only SINGLE PRECISION variables can be handled properly 
by these functions. Use the format conversion functions deser1bed~tateT — trr 
this section to derive the proper precision. 

RESULTS 

In all of these functions, vl will contain the result of the calculation 
if no error is detected. Any error (such as overflow, underflow, etc.) will 
leave the vl argument unchanged. The argument "v2" 1s not altered in any way 
by the functions. "*? 

RETURN CODES 



Each function has a return code of zero (0) if no errors occurred during 
the operation; otherwise, it will return a LEVEL II BASIC error code. The 
fcmpO function returns -1, 0, or +1 depending on whether vl 1s less than, 
equal to, or greater than v2. Typical error codes would be: 

2 - Syntax error 

5 - Illegal function call Clog (negative number)] 

6 - Overflow 

11 - Division by zero 
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DOUBLE PRECISION OPERATIONS 

The following functions can be used to operate on double precision 
fields (length 8). Their syntax is as follows: 



/ 



aS5$3S83S83S23S2«3 S3SSS38wS^3 ISS8X5@SSS883SS886383SS 23 8S £5 3 23533 85 25 S25s5 



j retcod » 


daddl 


I vl, 


v2 


); 


- 


vl a vl + v2 j 


I retcod • 


dsub< 


; vi. 


v2 


>; 


- 


vl ■ vl - v2 j 


I retcod » 


draull 


: vi, 


v2 


); 


m» 


vl ■ vl * v2 | 


I retcod ■ 


ddivl 


. vl, 


v2 


); 


- 


vl ■ vl / v2 | 


1 retcod ■ 


dabsl 


[ vl, 


v2 


>; 


- 


vl ■ abs(v2) j 


I retcod « 


dcmpi 


[ vl, 


v2 


>; 


- 


compare vl to v2 j 


1 retcod ■ 


dfixi 


£ vl, 


v2 


); 


- 


vl * fix(v2) | 


1 retcod ■ 


dint! 


! vl, 


v2 


); 


- 


vl « int(v2) | 


1 retcod ■ 


dsgnl 


[ vl 


)S 




- 


retcod * sgn(vl) 1 


1 vl & v2 


i 


ire the < 


iddress 


of doubl 


e precision fields. 1 



These functions perform calculations on two double precision fields and 
place the result in the first field specified in the argument list (vl). In 
the event of an error, vl is unchanged and can be examined to determine the 
cause of the error. Only DOUBLE PRECISION variables can be handled properly 
by these functions. Use the format conversion functions described later in 
this section to derive the proper precision. 

RESULTS 

In all of these functions, vl will contain the result of the calculation 
if no error is detected. Any error (such as overflow, underflow, etc.) will 
leave the vl argument unchanged. The argument "v2" is not altered in any way 
by the functions. 

RETURN CODES 

Each function has a return code of .zero (0) if no errors occurred during 
the operation; otherwise, it will return a LEVEL II BASIC error code as 
described in the list under SINGLE PRECISION. The dcmpO function returns -1, 
0, or +1 depending on whether vl is less than, equal to, or greater than v2. 



/ 



y 
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OATA CONVERSION FUNCTIONS 



The need will arise to convert between double precision, single 
precision, integer, and ASCII string. The following functions exist for this 
purpose: 

3»2S3S»aS3SIS33S3ISll3a333X32«33SSa3SSS3X3I333X33S33333OTa3: 



retcod 

retcod 

retcod 

intval 

retcod 

retcod 

retcod 

retcod 

retcod 

Intval 

dvar 

fvar 

Intval 

Ivar 

str 



■ atod( str, dvar ); 

■ atof( str, fvar ); 

■ dtoa( dvar, str ); 

■ dto1( fvar ); 

■ dtof( dvar, fvar ); 
« ftoa( fvar, str ); 

■ ftod( fvar, dvar ) 

■ itod( 1var, dvar ) 

■ 1tof( 1var, fvar ) 

■ ftoK fvar )» 



ASCII to double 
ASCII to single 
double to ASCII 
double to Integer 
double to single 
single to ASCII 
single to double 
integer to double 
integer to single 
single to integer 



r 



- specifies a double precision field. 

- specifies a single precision field. 

- specifies the integer value returned. 

- specifies an integer value. 

- specifies a character string field. 



The above conversions should be self-explanatory. The conversions not 
shown above that convert ASCII to integer and vice versa, are part of the 
standard library and are documented in a preceeding section of the LC 

LIBRARIES. 

The C itoi() function has not been implemented, for obvious reasons. 



y 
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FLOATING POINT EXAMPLE 

aissasassasszsisasssiss 

The following illustrates how the floating point library can be used in 
an application. The example is derived from K&R, page 8. 

/* fctab - print Fahrenheit-Celsius table 

for f » -8, 12, 32, ..., 312 */ 
linclude stdio/csh /* include standard header file */ 
#option fplib /* force search of FPLIB */ 

main() 

< 

int lower, upper, step, fahr; 

char celsius£4]; /* provide space for "float" */ 

char fivedivnine[43; /* space to hold (5.0/9.0) */ n 

char temp[43; /* temporary work space */ 

char thirty two [4]; /* space to hold 32.0 */ 

char celsius__strC8]; /* space for ASCII result */ 

lower » -8; /* lower limit of temperature table */ 
upper ■ 312; /* upper limit */ 
step a 20; /* steo size */ 
/* 

Note that the calculation (5.0/9.0) was removed from the 
body of the "while" loop to speed up calculations! 

atof("5.0\fivedivnine); /* float 5 */ 
atof( "9.0", temp); /* float 9 */ 
fdiv(fivedivn1ne,temp); /* calc 5.0/9.0 */ 

atof("32.0\thirtytwo); /* float 32.0 */ 

fahr * lower; /* initialize to starting value */ 

while ( fahr <* upper ) /* "fahr" & "upper" are integers */ 

itof(fahr,celsius); /* float fahr */ 
fsub(celsius.thirtytwo); /* fahr - 32.0 */ 
fmul(celsius,f1vedivnine); /* (5.0/9/0)*(fahr-32.0) */ 
ftoa(cels1us, Celsius str); /* result to ASCII */ 
printf("X-6.3d " X-8.8s\n\fahr,celsius_str); 
fahr +« step; /* note the assignment operator */ 
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ADVANCED TOPICS 
UTILIZING ASSEMBLY-TIME OPTIONS 



LC provides certain options which can help the programmer to generate 
efficient programs. These options can be specified from the C source code -by. 
using the #option statement. The defaults to these options are set in the 
file, LCMACS/ASM, so that no options need be set, except when the default is 
not the desired option. Since the #option statement generates a DEFL 
statement in the assembly language source output, it can also be used to 
control options in any user libraries or separately compiled modules. If used 
to control options in separately compiled modules, the loption statement must 
be in a module which precedes the module whose option is to be specified. 

Bear in mind that an option, once set, can be changed by an other /^option 
statement. Thus, when assembling separately compiled modules, care should be 
taken that a later module will not change the option set in the current 
module, unless this is desired. 

Options which are switches can be set to ON (-1) or OFF (0). These 
specify whether or not some option is to be active. The constants ON and OFF 
are defined in STDIO/CSH. Options which are not switches may be set to the 
value desired by specifying the value in the #option statement. 

ARCS 

This option controls the generation of argc and argv, the command line 
argument parsing. If the option is turned ON, the arguments are created and 
placed on the stack so that the user may access them from main(). If turned 
OFF, some savings in memory result, as no parsing of the command line is 
done. ARSS defaults to ON. For more information on argc and argv, see K&R. 

FIXBUFS 



This option, if set to ON, will cause standard I/O to pre-allocate all 
buffers needed for standard I/O. This eliminates the need for the dynamic 
memory functions to be loaded, and prevents users from locking themselves out 
from further fopenO's by allocating all of memory. This also guarantees that 
the standard I/O files can always be opened if the program is loaded. When 
dynamic allocation (fixbufs is off) is active, a program, once loaded, may 
not be able to allocate enough memory to open the standard files, resulting 
in an error message and an abort. 

FIXBUFS defaults to OFF. 

FPLIB 



Whenever the floating point library is to be accessed, this option MUST 

be specified. It controls the initialization to the '80 ROM, as well as the 

searching of the floating point library. For this reason, it must be included 

in EVERY module which uses floating point. However, it must never be turned 
OFF by a module. This will result in undefined symbols at assembly time if it 
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was previously turned ON. This option may be turned ON by the graphics ^ 

function in the standard library. 

Y 
FPLIB defaults to OFF, to avoid unnecessary linkage and searching. v 

KBECHO 

In certain types of programs, such as screen and graphics editors, the 
programmer may choose to disable the echoing of characters typed at the 
keyboard. However, for most programs it is desirable to be able to see what 
is being typed, even if standard output has been redirected. This option 
allows this flexibility. When ON, KBECHO will cause the getcO function to 
echo all characters input from the keyboard to the video. This holds true for 
ANY file opened as "*KI% not just the standard input. ^ 

KBECHO defaults to ON. 

MAXFILES 

tt>flV *M *■* tOf OBD <Ofe ■!* 

This option requires a numeric argument instead of OFF or ON, as it is 
not a switch. The number will be used to set up control storage for user 
files. The maximum number of files which can be opened at the same time is 
controlled by MAXFILES. The standard I/O files are not counted in this 
number. For example, if no user files were needed, then MAXFILES could be set 
to zero. MAXFILES also controls the number of buffers pre-al located when the ">\ 
FIXBUFS option is ON. Thus, 1t 1s best to use MAXFILES when FIXBUFS 1s 
specified to minimize the memory pre-al located for file buffers. y 

MAXFILES defaults to allow the user eight (8) concurrently opened files. 

REDIRECT 

The REDIRECT switch controls the I/O redirection feature of the standard 
library. When REDIRECT 1s ON, standard files can be redirected by command • 
line specification. When OFF, no redirection processing takes place, and the 
standard I/O -files are set up as permanently attached to the keyboard and 
screen. The REDIRECT switch overrides the ARGS switch; 1f REDIRECT 1s ON, 
ARGS is also forced to ON. 

REDIRECT defaults to ON. 

ZVAR 

The ZVAR switch can be used to invoke the initialization of all 
variables to zero. If ZVAR 1s not optioned, only space will be reserved for 
variables and their Initial values will be undefined. Note that this switch 
option may be turned off or on throughout the program. 
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SEPARATE COMPILATION 

isisisssisssaassiisx 

LC supports separate compilation: functions and modules can be compiled 
at different times, then assembled together to produce one program. This 
facilitates the creation of compiled function libraries, and results in great 
time savings. Commonly used functions can be compiled once, then only 
assembled into new programs, without recompiling. Large programs may be 
segmented and each segment compiled separately, then assembled as a whole. 
With the "extern" and "static" statements, the variables used in a module may 
be specified as external or local. 

When separately compiling modules which reference variables in other 
modules, two approaches may be taken to supply declarations for the shared 
variables. The "-global" option of LC may be turned off and on, so that only 
one module actually defines the space for global variables. The other method, 
which is the proper method and results in better structure in programs, is to 
define variables as extern when referenced by all but one of the modules. 

USING THE -GLOBAL OPTION OF LC 



All shared global declarations should be placed in a separate file, to 
be #include'd by all modules which use them. Only one module can have +Global 
specified when compiled; all other modules must be compiled with -Globals in 
the LC command line. It is usually convenient to use +Global when compiling 
the module containing main(). This method is not normally recommended. It is 
only supplied as a convenience to those attempting to compile extremely large 
programs already written without using extern and static. It is best to learn 
to structure your functions into "units": modules containing a set of related 
functions and their related internal and shared variables. 

USING EXTERN AND STATIC 



When writing a large program, it is best to try and logically structure 
your program into modules containing related functions with the data 
structures they use within the same module. Any data structures or functions 
in a module which need not be accessed by any external function can be 
declared as "static". These static functions and variables will be unique in 
name when assembled, and will not be accessible to other modules, so there 
will be no conflicts in naming. Those data structures and functions declared 
in the module which need to be accessed by functions in other modules should 
be declared without any storage class. This causes these functions and data 
structures to become "external", meaning that they are defined in this 
module, and can be accessed from other modules. When using a function or data 
structure declared in another module, the "extern" statement is used to 
declare the type of the object, "extern" is required for accessing variables 
outside the module. However, a function may be used without an "extern"; the 
compiler will assume that the function returns an integer value. If any other 
result is returned, the function must be declared "extern". 
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ASSEMBLING SEPARATELY COMPILED MODULES 

Each module must be read and assembled by EDAS in the same assembly. The 

*GET assembler directive is used for this purpose. A file should be created 

with *6ET statements for all modules to be included in a program. This file 

name is then specified as the program name when assembling when using LC/ASM. 

Here is an example of the GET file 

(listing of MYPRGG/ASM) 

*GET MYMAIN 
"GET MYFUNCS 
*GET MORECODE 

When assembling, load LC/ASM into EDAS and then issue the following 
<C>hange command: 

C/CPR06RAM/MYPR0G/ 

to set up the *GET filename. Then assemble as you would normally. 



..y 
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CREATING USER LIBRARIES 

•■aasassaasuisiaassaia 

We encourage LC users to create libraries of commonly used functions. 
This increases your productivity, since functions need not be rewritten for 
each program. A library should contain functions which are self-contained; 
i.e. they do not require the calling function to know about the library 
module's internal structure, and do not assume anything about data structures 
that the calling function declares. In structured programming lingo, library 
functions should be data-coupled and functionally cohesive. Also, functions 
should be tested and be well debugged before being placed in a function 
library. 



IN-LINE LIBRARIES 



<*! 



*\ 



A user library can be created by appending LC output (assembly source) 
files together. The assembly of each function in the library can be 
controlled by the IFREF pseudo-op available in EDAS. When you reference a 
user library function in your program, the subsequent assembly of the program 
will cause the IFREF to be true for that function. Otherwise, if you have not 
referenced (called) that function, IFREF is false, so the function is not 
assembled. This method is simple and does not require the use of the PDS 
utility. Its disadvantage is that the entire library must be read by EDAS 
even if some of the modules do not get assembled. The *SEARCH. directive for 
searching PDS libraries in EDAS is much faster for larger libraries. 

The creation of an in-line (one after another) library should go 
something like- this: The user types the following commands: 



EDAS YOU TYPE 



> 


I <ENTER> 


00100 


IFREF FUNCA 


00110 


<BREAK> 


> 


LFUNCA 


> 


IB 


02430 


END IF 


02440 


IFREF FUNCB 


02450 


<BREAK> 


> 


LFUNCB 


> 


IB 


04410 


END IF 


04420 


<BREAK> 


> 


W USRLIB:! 



(NOW IN INSERT MODE) 

(EXIT INPUT MODE) 

(LOAD THE FIRST FUNCTION) 

(INSERT TO BEGIN AFTER LAST) 



(BREAK TO EXIT INPUT MODE) 
(LOAD THE SECOND FUNCTION) 



(HIT BREAK TO EXIT INPUT MODE) 
(SAVE THE LIBRARY ON DRIVE 1) 
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Any number of functions can be added In this fashion, by appending to 
the existing library. Each function could also be edited separately and then T 

appended together with the LDOS APPEND command (use the STRIP parameter of 
APPEND to* remove the EOF byte (X'lA' ) from "library" when you are appending > 

another module). This process generates a library which looks like this: 

IFREF FUNCA 
(FIRST FUNCTION) 

ENDIF 

IFREF FUNC8 
(SECOND FUNCTION) 

ENDIF 
(AND SO ON...) 

* *J different approach is needed when several functions have been compiled 
together In the same LC invocation. A temporary label is needed to control 
the invocation of tie module. This type of cortstruct looks like this: 

SINVOKEJT &EFL ;0efault to no invocation 

IFREF FUNCA 
SINVOKE IT DEFL -1 ;6et it 

END IF 

IFREF FUNCB 
SINVOKE IT DEFL -1 ; Get it 

ENDIF 

IFREF FUNCC 
SINVOKE IT D£;FL -1 jGet it 
" ENDIF 

; Now invoke the module if needed 

IF SINVOKE IT 
( THE HODULE GOES HER! ) 
ENOJF 

*w * W1 !f the corsstTuct shown above, the module will be assembled if anv of 

ItlT^ZVZZt " is better to —«• the ^«"o f 

m h i!. 1 ;- llM ^" br »y ^ searched by EDAS sequentially from beginning to 
ELSE*?? l B Sr der . 1n wh1ch f «"c«ons are placed in the library becomes 

JE Ti5£y If t!J u S 1 SiiJ- th J lib T ary V alled by another functio " »™ n 

tpdfp Zt il tne " th ® cal1 ng function """St appear first. This is because the 
1 R !Lt°r ^ called f «nct1°n wm not be true until the calllna function is 
asj^led. So the general rule 1s: Calling functions flSt? iilT!d SSoil 

PDS LIBRARIES 

Data T Set[ lb Msf f™ S* "JJ h th t^ cm > Uer are Mtua,, > Pinioned 
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used to create and maintain PDS libraries. PDS members may be executable 
"A commands, data files, source files, etc. In the case of the LC libraries each 

PDS member is an assembly source module. EDAS searches PDS libraries by 
performing an IFREF check on each member name. Only those members which have 
been referenced but not as yet defined are read and assembled by EDAS. For 
the rest of this discussion we shall assume the reader has a working 
' knowledge of the PDS utility. 

The PDS(BUILD) command is used to create and initialize a PDS library. 
Once created, modules can be appended to the library using the PDS( APPEND) 
command. The function name in a module is limited to eight characters, with 
no underline allowed. When the module contains only one function, it 1s 
convenient to have the module name be the same as the function name. In this 
case the command: ^ 

pds( append) myfunc/asn ujy/Hb.pds 

is sufficient to add the function myfuncO to the library my/lib. Note that 
it is necessary to specify the password when Issuing a command which writes 
to a PDS. The (data) parameter tells PDS that the member is not an executable 
program 

When a module contains more than one function it becomes necessary to 

use a PDS map file. The entry point specified in the map file is not 

important. The names of all the functions in the module which are to be 

accessible when searching must be placed on one line in the map file. For 

■>v example, If a module file MYMOD/ASM contains three functions, fund, func2, 

' and func3, then the map file, MYMOD/MAP, would look like this: 

wywwd/asm, f uncl.il, f unc2,0, f unc3,0 

and the command to append the module to the library, MY/LIB: 
pds(a) mymod my/lib (map) 

PDS will assume that "mymod" has an extension of /MAP. The (map) 
parameter tells pds that MYMOD/MAP has the information needed to append the 
module. 

Unlike in-line libraries, the order in which members are appended to a 
PDS library does not affect the functioning of the library. EDAS continues to 
search the library until no further references can be satisfied by the 
library. Thus, members may be appended in any order, purged and reappended, 

etc. 
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LC ASSEMBLY LAMSUAGE OUTPUT STRUCTURE 



LC generates a rather unusual assembly output file. LC depends on 
certain macro's in the file, LCMACS/ASM, which maintain and provide access to 
two separate program counters. These macros allow LC to declare variables and 
define strings in the middle of a function, without interrupting the actual 
generation of code to perform the function. The macros also cause all 
variables and strings to be placed together at the end of the program. These 
macros MUST BE USED 1f you are interfacing (with assembly language) to the 
variables generated in a module compiled by LC. Failure to access variables 
using the macros will result in the wrong address being used. 



LC PROGRAM MEMORY MAP 



S-j 



LC programs, once assembled, have the following structure in memory: 



©START (usually 5200H) 

LC programs begin execution here. 

LC program initialization in LC/ASM. 

LC-generated modules, user assembly language 
modules. 

User library functions. 



SSSTORG 



All library functions from LC/LIB, FP/LIB, 
IN/LIB 



©PROGEND 



Program variables and strings generated with LC 
macros. 



aOMEM 



Memory allocated by sbrk(). In use by the program 
or maintained by allocO and freeO. 



Unused memory available from allocO or sbrk(). 



SP-1024 

LC program stack - local variables stored here. 
1024 bytes of unused space. LC always reserves IK 
for the program stack when requests for dynamic 
dynamic allocation of memory are made. 
HIGHS - 2-80 SP 
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LC MACROS 



It is important to understand how to use macros in order to directly 
interface to variables declared by LC programs. However, it is not necessary 
if you are writing a function which will not access LC-declared variables. 
For' more information on the use of the EDAS macro capability, see chapter six 
of the EDAS manual. 

The macros in LCMACS/ASM are as follows: 

$S0RG 



$S0RG switches the EDAS program counter to the variable storage area. 
The current executable program counter is saved in SSTEMP, to be restored by 
a SPORG macro. Anything assembled by EDAS after SSORG will be placed at the 
end of the program, past all code assembled in the SPORG (normal) sections. 

$P0RG 



This macro recovers the original program counter saved by the $S0RG 

macro. The variable storage program counter is also saved, so that the next 

$S0RG will continue where the last left off. WARNING: a SPORG must follow a 

SSORG only, not another SPORG. The proper program counter will be lost if a 
SPORG 1s done when not in the variable storage area. 

SVAR #NAME,#SIZE 



All external variables are declared by LC using the SVAR macro. A data 
area will be defined which is designated by the #NAME given, with the #SIZE 
given. Any references made to variables declared with the SVAR macro are made 
using the following macros: 

SLSTR 

This macro is used to prepare for the definition of a string. The HL 
register pair is loaded with the current storage program counter, and the 
EDAS program counter is switched to the storage area counter. The program 
counter must be in the program area before the SLSTR macro is used. 

SLDS #NAME 

This macro gets the address of the variable #NAME into the HL register 
pair. 
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SGETB #NAME 



This macro fetches the contents of the character variable #NAME into y 
the HL register pair. The H register will be loaded with zero, and L will 
contain the character. 

SGETW #NAME 

The SGETW macro fetches the two-byte integer stored at #NAME Into the HL 
register. 

SHS #NUM 

The SHS macro points HL to the value "SP+NUM" (SP refers to the stack 
pointer). It is used to obtain the address of a local variable. 

SPUTB #NAME 

The SPUTB macro writes the character in the L register into character 
variable at #NAME. 



SPUTW mmE 

The SPUTW macro will write the Integer value in HL into the two-byte 
integer variable at #NAME. 
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LC IDENTIFIER OUTPUT 

•BBS SS 3 SB 33 83 3 S 3 3 3 3 3631 S 31 3S 

LC makes extensive use of the u *M0D u directive in EDAS. This EDAS 
assembler directive causes a unique one or two character alphabetic string to 
be assigned to a SET/SEARCH module. This replacement string is incremented 
each. time another *M0D directive is encountered. Every occurance of •?• in a 
label is then replaced with the module's unique replacement string. For more 
information on the *M0D directive, see chapter five in your EDAS manual. The 
following table outlines the format of label generation from LC: 



j*-^ 



IDENTIFIER CLASS 



Temporary labels 

External identifiers 

-longer than 3 characters 
-3 characters or less 

Static identifiers 

-external to functions 
-internal to functions 

Goto labels 



LC OUTPUT 



$?# 

NAME 
NAME 
NAM$ 



NAME§? 
NAME0?* 

NAMES?* 



NAME, NAM 

# 



LC identifier, 1 to 8 characters, 
upper case 

The temporary label number 

The function number (within the module) 



ua33zs»ui»suis»i33iaatui»»:N3az3s»3Z3sa33»uiaxi* 



LC generates labels in this fashion so that static variables, external 
variables, and labels will not conflict with each other. Thus, there can be 
an external variable named x, a module static named x in two different 
modules, a static named x in two different functions in the same module, and 
a (goto) label named x, all within the same program, with no conflicts. The 
'?' module substitution character in the labels will make labels unique 
within each module, while the function number appended to labels will make 
labels unique within each function. A dollar sign, '$', is appended to 
external labels which are three characters long or less. This prevents 
possible conflicts with register names and logical operators in EDAS. 

Temporary labels are used by LC to implement conditional statements and 



operators, and loops. They are assigned numbers 
incrementing by 1. The dollar sign, '$', as the first 
suppress all temporary labels from your symbol table 
switch of the EDAS <A>ssemble command. The '?' makes 
within each module. 



starting at 1, and 
character allows you to 
output by using the -SL 
temporary labels unique 
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RUN-TIME SUBROUTINES 






A program generated by LC performs logical, arithmetic, and data 
manipulation operations through two registers: the HL and DE register pairs. 
HI is the primary register; DE is the secondary register. The stack is used 

Certain Operations are performed using subroutines in LC/LIB. These 
subroutines are: 

«S)>saaas8SBSsasaasass«aiiss«aaaas8siuis>asaB«s>ssBS«samsaaBsiai 



SUBROUTINE 



mm 

©PINT 

@0R 

@X0R 

@AND 

@EQ 

@NE 

§GT 

0LT 

©LE 

§GE 

@UGE 

@ULT 

@UGT 

§ULE 

§UCMP 

@ASR 

0ASL 

@NEG 

@C0H 

#N0T 

mini 

IDIV 



OPERATION PERFORMED 



get Integer in memory at (HL) into HL 

put integer in HL into memory at (DE) 

bitwise OR of DE with HL 

bitwise exclusive OR of DE with HL 

bitwise AND of DE with HL 

returns DE «■ HL 

returns DE !■ HL 

returns DE y HL 

returns DE < HL 

returns DE <* HL 

returns DE >» HL ~" 

returns unsigned DE >» HL 

returns unsigned DE < HL 

returns unsigned DE > HL 

returns unsigned DE <■ HL 

unsigned compare DE-HL non-destructively 

arithmetic shift right of DE by HL 

arithmetic shift left of DE by HL 

returns two's complement of HL 

returns one's complement of HL 

returns logical NOT of HL 

multiply 0£ ay HL to HL 

divide DE by HL, returns remainder in 

DE, quotient in HL 



av 
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ASSEMBLY LAN6UA6E INTERFACING 



While it is possible to insert assembly language source code directly 
into your LC program using the #asm-#endasm construct, it is much cleaner to 
interface by placing your assembly language code into a separate module. This 
keeps all the non-portable code separate from the portable LC code. It is 
best to call assembly language as a function, rather than including it 
directly into an LC function by mixing C and assembly source code. 

REGISTER USAGE 



All registers are available for use by the assembly language function. 

The only stipulation is that the stack pointer must be returned in the same 

condition as it was upon entry. — - 

ARGUMENT PASSING 



LC passes arguments on the Z-80 machine stack. Each argument is pushed 
onto the stack as a two-byte value. Arguments are pushed in order opposite of 
the order they are specified in the function call. Here is the assembly 
language which LC generates to perform a function call: 



x»func( 


a,b,c); 


LD 


HL,(C$) 


PUSH 


HL 


LD 


HL,(B$) 


PUSH 


HL 


LD 


HL,(A$) 


PUSH 


HL 


CALL 


FUNC 



This process generates the following structure on the Z-80 machine 
stack: 



(SP+6) 


«> 


<c> 


(SP+4) 


»»> 


<b> 


(SP+2) 


»»> 


<a> 


(SP+0) 


■»> 


return address 



That is how the arguments appear to the called function when first entered. 
There are several methods which can be used within the called function to 
obtain the arguments. The simplest method is to POP each argument off the 
stack. This is not suitable for large numbers of arguments, but most 
efficient for 3 operands or less. Using the example above, the arguments 
could be retrieved as follows: 

FUNC POP AF ;return address saved 
POP BC argument <a> in BC 
POP DE ;argument <b> in DE 

ASM ISTERFA£II!£ 
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POP 


HL 


; argument <c> in HL 


PUSH 


HL 


;restore argument <c> 


PUSH 


DE 


; ■ " <b> 


PUSH 


BC 


; " <a> 


PUSH 


AF 


;stack 1s same as at entry 
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Important to keep track of the stack pointer. However, the contents of the 
stack, i.e., the arguments, are "owned" by the called function and can be 
used like any local variable. A better method to use when dealing with large 
numbers of arguments is shown below: 



LD 


HL.2 


; offset to <a> 


ADD 


HL.SP 


;HL » address of <a> 


CALL 


@GINT 


;get contents of <a> 



0GINT is a run-time library function which gets the integer pointed to 
by HL into HL. See the previous section on LC assembly output structure for 
more information. 

Another method is to utilize the Z-80 index registers. The stack pointer 
must hi placed into the index register first- then index offset values Gin be 
used to get and store the arguments: 



LD 


IX.f 




ADD 


IX, SP 


;get SP into IX 


LD 


L,(IX+2) 


;get LSbyte of a 


LD 


H,(IX+3) 


;get MSbyte of a 



If an argument is intended to be a character variable, only • the least 
significant byte (LSbyte) 1s needed, so a single indexed load 1s used. 

LABELS AMD COMSTAMTS 

It Is strongly recommended that the assembly language programmer utilize 
the EDAS *M0D directive to assure that labels do not duplicate those In other 
modules. The following method will assure that you will not have this 
problem: 

*M0D 

VAR1§? DM 9 

EQU2@? EQU 2 

FUNC ; your function he.re... 

OR* * FUNC2@? ;go to temporary label 
. • . 
FUNC2®? ; temporary label 

By appending the $?, your label becomes unique from all others in an 
assembly, assuming that you placed a *M0D directive at the beginning of the 
module. Keep in mind, however, that other modules cannot get to these types 
of variables, since the '?• is substituted at assembly time. Labels which 
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must be accessed by other assembly language modules should be defined without 
the •?' in the label (i.e. to keep them global). 

If a variable must be accessed by an LC module which is to be defined by 
the assembly module, then the macros described earlier in this section must 
be used to declare the variable, and to access it. within the assembly 
language module. Examine the macros in LCMACS/ASM to see how they work, for 
additional interfacing ideas. 

RETURNING A VALUE 



LC programs use the HL register pair for a 16-bit accumulator. Any value 
to be returned by a called function must be placed in HL before returning to 
the calling function. Take care that a full 16-bit value is returned. If a 
character or 8-bit value is being returned, then H should be loaded with 
zero. If a true or false indication is to be returned, HL should be set to 1 
or 0, accordingly. 

CALLING MACHINE LANGUAGE ROUTINES 



The callO function has been provided in the installation library to 
standardize the invocation of machine language routines. The use of callO is 
documented on page 4-36 and illustrated in the program, syscaTl, which may be 
found in appendix D. 
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WHEN THINGS GO WRONG.*. 



r 

C is a language which offers great flexibility, but not without a price. — 

The price of C's freedom is the programmer' s ability to make catastrophic 
errors with ease. The programmer is not protected from himself when using LC. 
Youp best protection is to carefully check your programs when ~you write them, 
for any evident errors before you try to run them. Of course, any time you 
test a program you should not have any disks in your drives that you would 
care about if they were suddenly erased. This is not to say that you 
shouldn't experiment; quite the contrary. However, always be prepared for the 
worst. 

With LC, you have an advantage over other compilers. LC generates an 
assembly language source file. You can debug the program without 
second-guessing the compiler, or having to disassemble the compiled output. 
The modularity of the program also helps, since there are clear interfaces 
(functions) to breakpoint at. It would be helpful, though not essential, for 
the programmer to have familiarity with the 2-80 instruction set and with the 
debug facility of LOOS. 

COMPILATION ERRORS 

LC generates an error message whenever 1t finds something 1n the input ^»~v. 
file that cannot be recognized, or that doesn't fit the syntax of the C ""* > 
language. There are also some limitations in the LC Implementation which can u 
cause LC error messages to appear. When LC outputs an error message, it will 
print the line 1n error and point to the particular character where the error 
was recognized. The actual programming error 1s likely to be earlier in the 
program, depending on the type of error. 

Some errors may not be detected until many lines later. For example, if 
a closing brace is missing 1n the input file, LC will not be able to detect 
the error until the next function declaration, which will then be flagged as 
a function call without an ending semicolon. This is because LC thinks the 
previous function has not been completed. Similarly, If an opening brace 1s 
missing, LC will not find out until the last closing brace 1s encountered, 
with no match. 

In the appendix of this manual is a list of the error messages which LC 
can generate, and some likely causes for each. Most errors are usually 
typographical, but the user should be well versed in the C language and the 
LC Implementation. Learn where to find information regarding syntax and 
capabilities of the language. The language definition chapter of this manual 
and the appendix of the K&R text are good places to look when not sure of 
syntax. 
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ASSEMBLY ERRORS 



There are few assembly errors which can occur 1f you assemble your 
programs using LC/ASM and GET your compiled C modules. Your safest bet is to 
use LC/JCL when compiling and assembling. If you have written portions of 
your program in assembly language you may have a few more errors to deal 
with. Please read the previous section on assembly language interfacing for 
hints in debugging your assembly language. 

If you are creating a CMD file directly from the LC/JCL file, you will 
be aware of an assembly error if the JCL aborts from EDAS. To specifically 
isolate the assembly error, you will need to execute EDAS, load the^ LC/ASM 
file, globally change CPRQGRAM to the name of your C compiled output program, 
then assemble with the -WE switch. One of the following errors should 
prevail. 

UNDEFINED SYMBOL - A symbol which you referenced in your program was 
undefined in any module in your program. This can be caused by omitting the 
definition, misspelling the identifier, or defining them incorrectly. A look 
at the name which is undefined will give you a clue as to which situation was 
the cause. Misspelling should be obvious. Look out for upper-case versus 
lower-case names. Remember that LC is case sensitive. 

MULTIPLE DEFINITION - A symbol was defined twice with the same name. If 
you are assembling separately compiled or user library functions, you may 
have named two external variables or functions the same. To correct this, 
make one or both of the Identifiers static within the module. If separate 
compilation -is not being used, you have defined two external objects in your 
program with the same name. 

It is useful to familiarize yourself with the previous section on LC 
assembly language output structure. Also, If you are assembling separately 
compiled or user library functions, a good understanding of the "extern" 
statement and external versus static variables is essential. Refer to the 
section on storage classes in Chapter 2, LC Language Definition. 
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APPENDIX - OPERATORS 
f. -^ UNARY OPERATORS 

ft MMM9JMMMMM 38383531353 

* indirection (object at) . 2-17 

& pointer (address of) , 2-18 

negation 2-18 

1 logical NOT 2-18 

one's complement 2-18 

++ increment 2-18 

decrement 2-18 

BINARY OPERATORS 

* multiplication . 2-21 

/ division 2-21 

% modulus (remainder) 2-21 

+ addition 2-21 

subtraction 2-21 

« shift left 2-21 

» shift right 2-21 

< less than 2-21 

> greater than 2-21 

O less than or equal to 2-21 

>■ greater than or equal to 2-21 

■» equal to 2-21 

( "' N 1» not equal to 2-21 

W. & bitwise AND 2-21 

"-" " „. bitwise exclusive OR 2-22 

| bitwise inclusive OR 2-22 

Ui logical AND , 2-22 

|| logical OR ...'.':..! 2-22 

? : conditional ( if- then-else) _.. 2-2 2 

■ assignment 2-2T 

[+», _» f *», /», %= t «», »» t &« f -», |»] ... 2-23 
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ptr » alloc( nbytes ); 4„02 

retcod » atod( str, dvar ); 4-43 

retcod ■ atof( str, fvar ); 4.43 

int » atoi( decs ); .......!! 4-03 

retcod * box( funcod, xl, yl, x2, y2 ); ]'. 4-25 

retcod ■ call( address, regs ); 4.36 

retcod » circle( funcod, xl, yl, rl ); ] 4_25 

retcod ■ cmd( "command string" ); ...[ 4.35 

cadK "command string" ); ]] 4.35 

retcod ■ curposO; ]]* 4.35 

cursor( row, col ); 4.35 

retcod » dab$( vl, v2 ); 4.42 

retcod ■ dadd( vl, v2 ); 4_42 

date( s ); ." 4.35 ^ 

retcod » daap( vl, v2 ); j* 4.42 

retcod * dd1v( vl, v2 ); 4-42 

retcod » df1x( vl, v2 ); 4_42 

retcod - d1nt( vl, v2 ); 4-42 

retcod - dmul( vl, v2 ); 4-42 

retcod « dsgn( vl ); 4-42 

retcod • dsub( vl, v2 ); 4-42 

retcod ■ dtoa( dvar, str ); 4-43 

intval ■ dtoK fvar ); 4-43 

retcod ■ dtof( dvar, fvar ); 4-43 

ex1t( code ); 4-04 

retcod - fabs( vl, v2 ); 4-40 

n retcod » fadd( vl, v2 ); '. 4-40 

retcod » fatn( vl, v2 ); 4-40 

^ retcod - fclose( fp ); , 4-05 

retcod » fcaip( vl, v2 ); 4-40 

retcod » fcos( vl, v2 ); 4-40 

retcod » fd1v( vl, v2 ); 4-40 

retcod » fexp( vl, v2 ); 4-40 

retcod * ffix( vl, v2 ); 4-40 

eofind « fgets( buf, max, fd ); 4-06 

f111( buffer, count, char ); 4-34 

retcod » f1nt( vl, v2 ); 4-40 

retcod » flog( vl, v2 ); 4-40 

retcod - fmul( vl, v2 ); 4-40 

fp » fopen( fspec, mode ); 4-07 

fplnltO; 4 - 39 

retcod ■ fraise( vl, v2 ); 4-40 

retcod » fprintf( fp, control, argl, arg2, ... ); 4-08 

retcod ■ fputs( string, fp ); 4-0g 

free( ptr ); 4«10 

retcod * freeaeoO; 4-34 

retcod ■ frnd( vl, v2 ); 4-40 

retcod » fsgn( vl ); 4-40 

retcod « fsin( vl, v2 ); 4-40 

retcod » fsqr( vl, v2 ); 4-40 

retcod » fsub( vl, v2 ); 4-40 

retcod » ftan( vl, v2 ); ■. " 4.40 

retcod * ftoa( fvar, str ); '.'.'.'.'. 4-43 

retcod ■ ftod( fvar, dvar ); '..'.'.'.' 4-43 
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intVal * T bOl V TV HP )» ..aaaaaaeaa.....aaaaaaa.....aa.. 4—43 

C §CkCV IP /» aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaasaaaa 4— li 

C QStCnfij V / , aaaaaaaaaaaaaaaaa.aaaaaaaaaaaaa.«.«««aaa 4— J.2 

CUT Illu yCt*S\ OUTTSIr /, aaaaeaaaaaaeaoaaaaaaaaaaaaaaaa 4— X%J 

retCUU lIlK@Jr\ / , aeaaoaaaaaaaa. a. ...... ........ ....... 4—34 

■ *S l»W WVI I ll|#Ufl l» \ &JUI I* / s o.o.qqqqqqo..oqoqooo.qoo.0.q.o ^— <3^ 

retcod » 1salpha( char ); 4-15 

retcod * 1sd1g1t( char ); 4-15 

retcod * 1slower( char ); 4-15 

retcod ■ 1supper( char ); 4-15 

IbOov lilt j Q6CS /, a a a a a a a a a a a a a a a a a a a a a a a a a a a a • • a a a •'. o 4— )0«J 

retcod » 1tod( ivar, dvar ); 4-43 

retcod « ItofC ivar, fvar ); 4-43 

1 bWA \ lilt j ll6Ad / 9 ao««»«»0*»a«o«aa»»««««eaea««s«**»«a* *f ""iff J 

retcod ■ 11ne( funcod, xl, yl, x2, y2 ); 4-25 

«ove( pfrom, pto, Ten ); 4-14 

UUfcpOrbV pOrt, ValUe }J ....*aaaaa*«.....a...«.aaoaaas. 4—35 



retcod « pixel 
p1oc( address 
retcod « pmde 
retcod * point 
pr1ntf( contro 



rUflCQOt *» jf '» eaaaaaaaaoaeaaaaaaaaaaa 4— tii 

•i 4-27 

quadrant )j 4-27 

x. y ); 4-23 

I, argl, arg2, ...); 4-16 

cret a putc( c» fd ); .............. aa.aaaa .a aaa. .a.... 4-17 

cret » putchar( c ); 4-18 

retcod • pyts( string ); -4-19 

""** »\ * » y / » «... .«*.>...«....... a. ..aa«>. ..«••»*.... 4—23 

P tr * SDnC ( nOyteS ) » .*».•».«.•...••.••.•••••••••••.,. 4-20 

•"•* *» y '» aa.aaeasaeeoe.aa... ....«.«....•.••••...... 4—23 

StiXStv deSt, SOUrCe )J a. ea. ........ ••.•••...•.••..... 4-30 

retcod - strcmp( source, dest ); 4-30 

SfefXpyl OeSb, SOUrCe /| a. a .....a........ ...•.■••••.... 4—31 

retcod « strep! ( source, dest, pos, count ); 4-31 

sfcrept( dest, source, repeat ); 4-31 

retcod ■ strfitwK dest, source, pos ); 4-32 

Str1ght( dest, source, count ); 4-32 

strleft( dest, source, count ); 4-32 

retcod * strl@n( source ), 4-32 

retcod ■ stra.d( dest, source, pos, count); 4-32 

t1«e( s ); 4-35 

c ■ tolo»er( char ); , 4-21 

c ■ toupper( char ); 4-21 

in t xmjsv nexs 11 .................■•....••••••••.... 4—03 
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LC ERROR MESSAGES 

iHunaiuniiii 

64> "already defined" - The object being declared has already been defined 
in the module. 

65> "argument error" - The expression just processed caused LC to input the 
next line before the function call was completely processed. See the "split 
function call" error for additional information. 

66> "bad label" - The label specified in a "goto" statement was not a valid 
LC identifier. 

67> "expected comma" - The context of the input required a comma, 'but none 
was found. 

68> "function not declared" - The context of the input demanded that a 

function be declared, i.e., the input did not match anything which could be a 

compiler directive or a variable declaration, so it was assumed that a 
function was being declared. 

69> "global symbol table overflow" - LC ran out of global symbol table 
space. Either decrease the amount of memory reserved in high memory (see "not 
enough memory" error) or split the module being compiled into smaller modules 
with fewer external variables. 

70> "illegal address" - the "&" (address of) operator was used with an 
expression which was not an object in memory. 

71> "illegal argument name" - The argument name is not a valid LC 
identifier. 



72> "illegal identifier" - The input was interpreted as an identifier, but 
did not conform to LC's rules for identifiers. 

73> "input file open failure" - An input file could not be opened 
successfully. 

74> "invalid expression" - The input could not be recognized as an 
expression when the context of the program required an expression. 

75> "invalid option name" - The name given in a "#option" compiler directive 
was not a valid LC identifier. 

76> "invalid option value" - The value given in the "#option" compiler 
directive was not a character literal or numeric constant. 

77> "local symbol table overflow" - LC ran out of local symbol table space. 
Either decrease the amount of memory reserved in high memory (see "not enough 
memory" error) or decrease the number of local variables in the function. 

78> "line too- long" - The input line exceeded the maximum input line size 
allowed by LC (128 characters/line). 
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79> "macro table full" «• The current "tdefine" caused the table space 
allocated by LC to be exceeded. Either decrease. the amount of memory reserved 
in high memory (see "not enough memory" error) or decrease the number of 
"#define a statements in the module. 

80> "missing •:'■ -A "?" operator was found without a matching":'' 
operator. • 

81> "missing apostrophe* - A character literal was not ended with an 
apostrophe. LC does not allow a character literal to be continued on another 
line 

82> "missing bracket" - The ending "bracket" character shown in the error 
message was expected, but was not found. *? 

83> "missing quote" - A string literal did not have an ending quote ('"'). 
Strings cannot be continued on another line. ' 

84> "missing semicolon" - No semicolon was found at the end of a statement. 
The ' ;• character is the statement terminator, and must be placed at the end 
of a simple statement. 

85> "must be constant" - The size of an array must be a numeric constant. 

86> "must be extern" - a function declaration was encountered past a comma 
in an external (but not "extern") declaration statement. This context implies 
that the function is of storage class, "extern", but this was not the class 
of the declaration statement. 

87> "must be lvalue" - The expression being processed specifies that a value 
be placed into an object, but no object which could be stored Into was found. 

88> "negative size Illegal" - An array with a negative size was declared. 
The array size Is made positive before being used. 

89> "nested too deep - Ignored" -. The #include statement would have nested 
too deeply, if not ignored. Up to eight (8) nesting levels are available in 

9H> "no closing brace" - The end of the last Input file was encountered 
without a closing brace for the current function being found. 

9 J? /? . 1nput file " " No in P ut files were specified on the command line 
which Invoked LC. 

92> "no multiple dimensions" - The array being declared has more than one 
dimension, which is not supported. LG supports one-dimensional arrays only. 

sTatem^n? fSllowedlt?" d0 " " * W statement was com P 1led » but no "while* 

94> "not a pointer expression" - the indirection operator, "*" was used 
with an expression which does not result in the address of an object in 
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> 95> "not enough memory" - When LC began execution, not enough memory was 
free for LC to execute properly. Decrease the amount of modules in high 
memory (filters, MINIDOS, KSM, SYSRES'ed overlays, etc.) and try to execute 
LC again. 

96> "output file error" - An error occurred while writing to the output 
file. 

97> "output file open error" - An error occurred when attempting to open the 
LC output file. 

98> "split 'for'* - The expressions in parentheses in a for statement must 
appear on the same line. This is a limitation of the LC implementation^ not a 
limitation of the C language^ 

99> "split function call" - All the arguments in a function call must be 
given on the same line. This is a limitation of the LC implementation, not a 
limitation of the C language. 

100> "too indirect" - The expression exceeded the amount of indirection 
allowed by the declaration of the objects used in the expression. 

101> "too many active loops" - LC allows nesting of loops and "switch" 
statements to 25 levels. The loop or "switch" being processed would have 
nested more than 25 levels. 

vy' 102> "too many arguments 61 - There were too many arguments specified in a 

function call. LC limits the number of arguments in a function call to 16. 

This is a limitation of the LC implementation, not a limitation of the C 
language. 

103> "unmatched arguments" - The argument being declared did not match any of 
those in the argument list for the function. 

104> "unrecognizable declaration" - The object being declared contains a 
character which is invalid in the context of a declaration. 

105> "unrecognizable option" - One of the options specified in the command 
line was not a valid LC option. 
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/* CAT/CCC */ 

/* Utility to concatenate files to standard output */ 

/* adapted from "The C Programming Language" by */ 

/* Kernighan and Ritchie. */ 

#include stdio/csh 

FILE *fp; 

main ( argc, argv) 

int argc,*argvG; 



{ 



if (argc -■ 1) /* no args, copy standard input */ 

filecopy(stdin); 
else 

while (—argc) 

{ if ((fp » fopen(*++argv,"r")) «- NULL) 
{ fputs(*argv); 

abort(" - open error."); 
} 

else 

{ filecopy(fp); 
fclose(fp); 



> 

filecopy(fp) 
FILE *fp; 



/* copy a file to the standard output */ 



int c; 

while ((c * getc(fp)) !- EOF) 
If (c !» putc(c.stdout)) 

abort( "Output file write error"); 

abort(msg) 
char *msg; 

fputs(msg.stderr); 

putc(eol.stderr); 

exit(l); /* let system know about the error */ 
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/* Test of cmdK) */ ^ 

#1nc1ude stdio/csh 

#opt1on INLIB 

char bufClM]; 

ma1n() 

{ putsCTest of ond1()\n\n"); 

puts ("Enter corasiands*); 

gets(buf); 

crodl(buf); 
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/* Test of cmdO */ 

#include stdio/csh 

#option INLIB 

char buf[100]; 

mainO 

{ int re; 

putsCTest of cmd()\n\n M ); 
puts("Hit break to exit back to D0S\n"); 
while (TRUE) 

{ puts ("Enter command:"); 
if (gets(buf)-NULL) 

ex1t(0); 
rc»cmd(buf); 
printf("\nReturn code is Xd\n",rc); <^- 

} 

} 



'5b-- 
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/* compare/ccc */ 

#1nclude stdio/csh 

int line, cl, e2; > 

FILE *fpl,*fp2; 

main (argc 9 argv) 

{ if (argci®3) 

{ puts ("Format error: compare filel file2\n"); 

exitO; 
} 

line «1; 

fpl « getfile(*-H-argv); 
fp2 « getfile(*++argv); 
while ((d * getc(fpl)) J » EOF & ^ 

(c2 » getc(fp2)) !- EOF) 
{ if (cl 1» c2) 

{ printf ("Difference at line %-10d\n\ line); 
exit( ); 

} 

else if (cl ** eol) +-Hine; 
> 
if (cl »»c2) 

puts ("The files are equal \n"); 
else 

puts ("The files are not of equal length\n"); - 

getf11e(fnat»e) ,-" 

char *fname; ' , L 

< char *fp; 

if ((f.p»fopen(fnajne, 68 r®)) »« NULL) 

< pr1ntf(*Qpen error - %-2|ls\n ,l ,fnaitie); 
exitO; 

> 

else return fp; 
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/* decom/ccc */ 

/* comment stripper program - 09/14/82 */ 
/* removes all comments and multiple white spaces */ 
#define eof -1 
#define eol 13 

int col, tab, string, comment; 
int c; 
main() 

{ col ■ tab ■ comment » string ■ 0; 
while ( (c»getchar() ) !■ EOF) 
{ if (comment) 

{ if (c*»eol) tab ■ comment ■ string » 0; 

else continue; 
} 

else if (c"-';*) 
if (1 string) 
{ comment * 1; 

continue; 
} 
else if (c*»eol) 

tab»string»0; 
else if (c*»'V ' ) 

string * ! string; 
if (whitespace(c)) 

{ tab * 1; continue; } 
else if ( tab ) 

{ putchar('\t'); tab - 0; col++; } 
if (c ■■ eol ) 

{ if ( col *» ) 

continue; 
else col * -1; 
} 
putchar(c); col+t; 
} 
exit(0); 

} 

whitespace(c) 
int c; 



{ 



} 



if (c »- '\f | c — •• ') 

return (1); 
else 

return (0); 
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/* Plot Hilbert curves of orders 1 to n */ 

#1nclude stdio/csh 

#option INLIS 

1nt h,x,y,x0,y0,u,v; 

mainO 

{ int i,n, h0; 

putsCXxPAxlcXxlf hllbert curvesXn"); 
n » 4; h0 - 32; 
i*0; h«h0; x0*h / 2; y0*x0; 
while ( 1 < n ) 
{ 

h ■ h / 2; 

x0 * x0 + h / 2; y0 * y0 + h / 2; 
x « x(5+ 1 * 32; y « y0+10; u»x; v»y; 
+♦1; p(l.i); ^ 

} 
exit<0); 
) 
raove( ) 

{ int i s j; 

for (1>m1n(x!u) ; i < (max(x,u)+l) ; i++) 
for (jsis5lr.{j f ¥) ; j < (nAx^vHl) ; 1**) 
pixel(l,i,j); 
u»x; v s y; 
return (0); } 
ra'ln(a,b) 
int a,b; 

{ 1f (a > b) retum(b); else return(a); } 
raax(a 8 b) 
int a,b; 

{ if (a < b) return(b); else return(a); } 
p(typ 8 i) 

int typ, i; 

{ if (i <- 0) return(0); else 
switch (typ) { 

case Is p(4j,1-;Uj x » x«h; saove{); 
p(l,1*l); y * y-h; moveO; 
p(l,i-l); x " x+h; noveO; 
p(2,1-l) ; break; 
case 2: p(3,i-l); y ■ y+h; moveO; 
p(2,i-l); x • x+h; raoveO; 
p(2,i-l); y ■ y-h; r»ove(); 
p(l.i-l) ; break; 
case 3: p(2,i-l); x * x+h; moveO; 
p(3 s i-l); y ■ y+h; moveO; 
p(3,1-l); x ■ x-h; moveO; 
p(4 8 1-l) ; break; 
case 4: p(l,1-l); y « y-h; moveO; 
p(4,i-l); x * x-h; moveO; 
p(4,i-l); y » y+h; moveO; 
p(3,i-l); break; 
} 

return (0); 
> 
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/* linetest/ccc */ 

#inc1ude stdio/csh 

#option INLIB 

mai n ( ) 

< 

1nt xl,x2,yl,y2,t,tl; 
puts( M \xlc\xlf"); /* clear the screen */ 
for ( xl-0, yl=0, x2»127, t « (J ; t <« 47 ; t++ ) 
{ lined, xl,yl,x2,t); 
line(0,xl,yl,x2,t); 

> 
for ( y2»47,t « 127 ; t >» ; t— ) 
{ lined, xl,yl,t,y2); 
line(0,xl,yl,t,y2); 
} 
exit(0); 
> 
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/* xfer/ccc */ -^ 

#inelude stdio/csh /* standard I/O definitions */ 

/* XFER - copy standard input to standard output */ )■ 

int c, bytes, lines; 

FILE *fp; 

roainO 

{ 

bytes » lines a 0; 
while( (e»getchar()) !* EOF) 
{ putchar(c); 
•H-bytesj 

if ( C »* EOL) ++lines; 
} 

fp - f open ("*do ",%"); 

fprintf(fp, "%d characters , %d lines", bytes, lines); ^ 
) 



)y 
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The following example program may help to illustrate the use of 
callO. The program was provided by Rich Deglin. 

/* test of syscalK) */ 

#define CKDRV 0X44B8 /* Note vectors are Model I */ 

#define DATE 0X4470 

#define DODIR 0X4463 

#define DSPLY 0X4467 

#define TIME 0X446D 

#define AF 

#define BC 1 

#define DE 2 

fdefine HL 3 

#define IX 4 <*? 

#define IY 5 

#define CARRY 

#option INLIB 

int rc,d; 

char *regs[6],buf[100]; 

main() 

{ putsCTest of call()\n\n ,, ); 

for (d=0;d<8;++d) 

{ regsCBOd; 

rc»call( CKDRV, regs); 

printf(-Drive %d %s%s\n",d,rc?"not ":"", "ready"); 

if (regsCAF]&(l«CARRY)) 

puts("Drive is write protected\n")i } 

wait(); 

dt (DATE, "Date"); 

dt(TIME,"Time"); 

regs[HL>"This is a message\n"; 

call (DSPLY, regs); 

wai t ( ) * 

regsL"BC3=(4«8)+0; 

regs[HL>buf; 

call (DODIR, regs); 

strmid(buf+80,buf,0,8); 

strmid(buf+90,buf,8,8); 

printf("%s Xs free: XdK\n\n",buf+80,buf+90,buf[18]+(buf[193«8)); 

regs[BC>0; 

call (DODIR, regs); 

waitO; 
> 

wai t() 

{ puts("\nHit any key"); getcharO; clscrnO; } 
dt(addr.str) 

char *addr,*str; 
{ regs[HL>buf; 

call(addr.regs); 

*regs[HL>0; 

printf("Xs: %s\n\str,buf ); 
> 

clscrnO 
{ puts("\xld\xlf»); return 0;> 
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